winwatch 0.1.0

data/lib/winwatch/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Winwatch
+  VERSION = "0.1.0"
+end

data/lib/winwatch.rb

@@ -0,0 +1,688 @@
+# frozen_string_literal: true
+
+require "winwatch/version"
+require "winwatch/winwatch" # native extension: Watcher + errors + _parse/_long_path
+
+# winwatch — watch a directory tree the way Windows means it: one
+# ReadDirectoryChangesW watcher with lossless overflow signaling (:rescan, never
+# silent drops). Parks fibers on the winloop IOCP when a scheduler is active, a
+# plain blocking pull everywhere else.
+#
+#   require "winwatch"
+#
+#   Winwatch.watch("C:/projects/app", recursive: true) do |w|
+#     w.each do |e|
+#       case e.type
+#       when :renamed then puts "#{e.from} -> #{e.path}"
+#       when :rescan  then full_resync!   # kernel dropped the backlog
+#       when :gone    then warn "watch died (#{e.code})"; break
+#       else               puts "#{e.type} #{e.path}"
+#       end
+#     end
+#   end
+module Winwatch
+  # ---- Win32 notify-filter flag values (verified, rdcw §3) ----
+  FILTER_FLAGS = {
+    file_name:   0x001,  # FILE_NOTIFY_CHANGE_FILE_NAME   -> :added/:removed/:renamed for files
+    dir_name:    0x002,  # FILE_NOTIFY_CHANGE_DIR_NAME    -> :added/:removed/:renamed for directories
+    attributes:  0x004,  # FILE_NOTIFY_CHANGE_ATTRIBUTES  -> :modified
+    size:        0x008,  # FILE_NOTIFY_CHANGE_SIZE        -> :modified
+    last_write:  0x010,  # FILE_NOTIFY_CHANGE_LAST_WRITE  -> :modified
+    last_access: 0x020,  # FILE_NOTIFY_CHANGE_LAST_ACCESS -> :modified (noisy; opt-in)
+    creation:    0x040,  # FILE_NOTIFY_CHANGE_CREATION    -> :modified
+    security:    0x100   # FILE_NOTIFY_CHANGE_SECURITY    -> :modified
+  }.freeze
+
+  DEFAULT_FILTER  = %i[file_name dir_name last_write size].freeze # rdcw §3 recommendation
+  MIN_BUFFER_SIZE = 4_096   # .NET FSW floor (rdcw §4)
+  MAX_BUFFER_SIZE = 65_536  # SMB protocol cap; non-paged-pool sanity (rdcw §4)
+
+  # ---- FILE_ACTION_* values (verified, rdcw §3) ----
+  ACTION_ADDED            = 1
+  ACTION_REMOVED          = 2
+  ACTION_MODIFIED         = 3
+  ACTION_RENAMED_OLD_NAME = 4
+  ACTION_RENAMED_NEW_NAME = 5
+  ACTION_RESCAN           = -1 # synthetic, from a malformed record chain (_parse)
+
+  # ---- completion-classification Win32 codes (§5.0) ----
+  ERROR_NOTIFY_ENUM_DIR    = 1022 # overflow, failure spelling -> :rescan
+  ERROR_OPERATION_ABORTED  = 995  # a cancel (ours or thread rundown)
+  ERROR_NOTIFY_CLEANUP     = 745  # our own handle close completed the op
+  ERROR_ACCESS_DENIED      = 5    # root delete-pending -> :gone
+
+  # A frozen event. Struct supplies deconstruct/deconstruct_keys for pattern
+  # matching: `event in {type: :renamed, from:, path:}`.
+  #
+  #   type  - Symbol: :added :modified :removed :renamed :rescan :gone
+  #   path  - String, absolute, UTF-8, forward-slash separated (watch root for
+  #           :rescan/:gone)
+  #   from  - String (old absolute path) for :renamed, else nil
+  #   code  - Integer Win32 error for :gone, else nil
+  Event = Struct.new(:type, :path, :from, :code)
+
+  # A Windows API failure carries the originating error code (set in C).
+  class OSError
+    def code
+      @code
+    end
+  end
+
+  module_function
+
+  # The only constructor. Resolves +path+ with File.absolute_path, opens the
+  # directory and issues the first ReadDirectoryChangesW before returning (so
+  # changes between watch and the first take are captured). Selects the mode
+  # once: :winloop when Fiber.scheduler&.respond_to?(:await_op) at call time,
+  # else :standalone. Yields the watcher (ensure-closed) when a block is given.
+  #
+  # Raises: Winwatch::NotFound / NotADirectory / AccessDenied / Unsupported /
+  # OSError (open/first-issue), ArgumentError / TypeError (bad options).
+  def watch(path, recursive: false, filter: DEFAULT_FILTER,
+            buffer_size: MAX_BUFFER_SIZE, normalize_names: true)
+    abs   = File.absolute_path(path.to_s)
+    keys  = filter_keys(filter)
+    flags = keys.inject(0) { |acc, k| acc | FILTER_FLAGS[k] }
+    bytes = normalize_buffer_size(buffer_size)
+    sched = Fiber.scheduler
+    winloop = sched.respond_to?(:await_op)
+
+    watcher = Watcher.send(:build, abs, keys.freeze, flags, recursive ? true : false, bytes,
+                           normalize_names ? true : false, winloop, sched)
+    return watcher unless block_given?
+
+    begin
+      yield watcher
+    ensure
+      watcher.close
+    end
+  end
+
+  # Run a blocking native call cooperatively. Under a Fiber scheduler (without
+  # await_op — async, winloop 0.1) the call is offloaded to a worker Thread so
+  # the calling fiber parks (Thread#value routes through the scheduler) and the
+  # loop keeps serving; 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 or consume data destined for a later op.
+  #
+  # Caveat: if the fiber is unwound (e.g. Timeout) in the instant after the
+  # worker's _take returned a batch but before Thread#value delivered it, that
+  # batch is lost with the killed worker — the documented winipc lost-
+  # acquisition window (the in-C stash, §5.12, does not cover this path).
+  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
+
+  # nil -> -1 (INFINITE); non-negative seconds -> ms, tiny positive rounds up to
+  # 1 ms (never collapses to a poll); negative -> ArgumentError.
+  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
+
+  # Validate the filter (non-empty Array of FILTER_FLAGS keys; a lone Symbol is
+  # wrapped) and return the de-duplicated key Array in the requested order.
+  def filter_keys(filter)
+    keys = filter.is_a?(Symbol) ? [filter] : filter
+    unless keys.is_a?(Array) && !keys.empty?
+      raise ArgumentError, "filter must be a non-empty Array of #{FILTER_FLAGS.keys.inspect} (got #{filter.inspect})"
+    end
+
+    keys.each do |key|
+      unless FILTER_FLAGS.key?(key)
+        raise ArgumentError,
+              "unknown filter flag #{key.inspect}; expected one of #{FILTER_FLAGS.keys.inspect}"
+      end
+    end
+    keys.uniq
+  end
+
+  # Validate buffer_size (Integer 4_096..65_536) and round up to a multiple of 4
+  # (DWORD alignment). Out of range -> ArgumentError.
+  def normalize_buffer_size(size)
+    n = Integer(size)
+    unless n.between?(MIN_BUFFER_SIZE, MAX_BUFFER_SIZE)
+      raise ArgumentError,
+            "buffer_size must be #{MIN_BUFFER_SIZE}..#{MAX_BUFFER_SIZE}, got #{size.inspect}"
+    end
+
+    (n + 3) & ~3
+  end
+
+  private_class_method :filter_keys, :normalize_buffer_size
+
+  # The directory watcher. Constructed only through Winwatch.watch (.new is
+  # private). The native superclass supplies the underscore-private primitives
+  # (_open / _take / _issue / _cancel / _close_* / closed? / _parse bridge).
+  class Watcher
+    private_class_method :new
+
+    # ---- construction (internal; called by Winwatch.watch) -----------------
+
+    def self.build(abs, keys, flags, recursive, bytes, normalize, winloop, sched)
+      watcher = _open(abs, flags, recursive, bytes, winloop)
+      watcher.send(:init_state, abs, keys, recursive, bytes, normalize, winloop, sched)
+      watcher
+    end
+    private_class_method :build
+
+    def init_state(abs, keys, recursive, bytes, normalize, winloop, sched)
+      @path        = abs.dup.freeze
+      @filter      = keys.dup.freeze
+      @recursive   = recursive
+      @buffer_size = bytes
+      @normalize   = normalize
+      @mode        = winloop ? :winloop : :standalone
+      @pending_old = nil # cross-call carry is NOT used; adjacent-only (§5.8)
+
+      start_pump(sched) if winloop
+      self
+    end
+    private :init_state
+
+    # ---- public accessors --------------------------------------------------
+
+    attr_reader :path, :buffer_size, :mode
+
+    def recursive? = @recursive
+    def filter     = @filter
+
+    # ---- the blocking pull -------------------------------------------------
+
+    # Returns a non-empty Array of Winwatch::Event as soon as any are available,
+    # or nil on timeout. timeout: nil = forever; non-negative seconds otherwise
+    # (ArgumentError if negative); 0 is a non-blocking poll. Raises
+    # Winwatch::Closed if the watcher is (or becomes) closed.
+    def take(timeout: nil)
+      ms = Winwatch.ms_for(timeout)
+      @mode == :winloop ? take_winloop(ms) : take_standalone(ms)
+    end
+
+    # Yield events one at a time, forever. Returns nil after a :gone event (the
+    # terminal event), or when the watcher is closed from elsewhere (it swallows
+    # the Closed raised by its own internal take). Block required.
+    def each
+      raise ArgumentError, "Winwatch::Watcher#each requires a block" unless block_given?
+
+      loop do
+        batch =
+          begin
+            take
+          rescue Closed
+            return nil
+          end
+        next if batch.nil?
+
+        batch.each do |event|
+          yield event
+          return nil if event.type == :gone
+        end
+      end
+    end
+
+    # ---- standalone take ----------------------------------------------------
+
+    def take_standalone(ms)
+      # Track a monotonic deadline for a finite wait so a benign housekeeping
+      # completion mid-wait (a 995 self-heal, a 745, or an aborted op that
+      # re-armed cleanly -> an empty classification) does NOT masquerade as a
+      # timeout: we keep waiting out the REMAINING time rather than returning nil
+      # the instant such a completion intervenes (§2.5/§5.17). nil only on the
+      # real deadline. Infinite waits (ms<0) loop forever as before.
+      deadline = ms.negative? ? nil : (monotonic + (ms / 1000.0))
+      slice = ms
+      loop do
+        result = Winwatch.run_blocking { _take(slice) }
+        case result
+        when nil
+          return nil # timeout
+        when :closed
+          raise Closed, "winwatch: watcher is closed"
+        else
+          data, code, rearm = result
+          events = classify(data, code, rearm)
+          unless events.empty?
+            # A terminal :gone auto-closes the watcher (§2.5): the next take
+            # raises Closed. Close after building the batch so this batch is
+            # still delivered.
+            close if events.any? { |e| e.type == :gone }
+            return events
+          end
+          # An empty result means "no event, re-armed, keep waiting". Loop
+          # forever on an infinite wait; on a finite deadline, recompute the
+          # remaining time and keep waiting until it is actually exhausted.
+          next if deadline.nil?
+
+          remaining = deadline - monotonic
+          return nil if remaining <= 0
+
+          slice = Winwatch.ms_for(remaining)
+        end
+      end
+    end
+    private :take_standalone
+
+    # ---- :winloop take ------------------------------------------------------
+
+    def take_winloop(ms)
+      deadline = ms.negative? ? nil : (monotonic + (ms / 1000.0))
+      @mutex.synchronize do
+        loop do
+          unless @events.empty?
+            batch = @events
+            @events = []
+            return batch
+          end
+          raise Closed, "winwatch: watcher is closed" if drained_and_dead?
+
+          remaining = remaining_slice(deadline)
+          return nil if remaining && remaining <= 0
+
+          @cond.wait(@mutex, remaining ? [remaining, 0.1].min : 0.1)
+        end
+      end
+    end
+    private :take_winloop
+
+    # True once the queue is empty AND the watcher is closed or its pump is dead
+    # (so take/each raise Closed instead of parking forever, §6.1 dead-pump).
+    def drained_and_dead?
+      return false unless @events.empty?
+
+      @closed || pump_dead?
+    end
+    private :drained_and_dead?
+
+    def remaining_slice(deadline)
+      return nil if deadline.nil?
+
+      deadline - monotonic
+    end
+    private :remaining_slice
+
+    def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    private :monotonic
+
+    # ---- close / closed? ---------------------------------------------------
+
+    # Cancel the in-flight op, close the directory handle, and wake any blocked
+    # take (which raises Closed). Pending not-yet-taken events are discarded.
+    # Idempotent; safe from any thread/fiber. After :gone the watcher is already
+    # closed; calling close again is a no-op.
+    def close
+      @mode == :winloop ? close_winloop : close_standalone
+      nil
+    end
+
+    def close_standalone
+      _close_standalone
+    end
+    private :close_standalone
+
+    def close_winloop
+      @issue_lock.synchronize do
+        @closed = true
+        _mark_closed
+        _cancel
+      end
+      # Wake a parked consumer and wait (bounded) for the pump to finish so the
+      # handle is closed in the cancel -> reap -> close order. On a dead pump,
+      # fall through to _close_handle directly.
+      signal_consumers
+      wait_for_pump_done
+      nil
+    end
+    private :close_winloop
+
+    # closed? is defined in C (raw getter; works on closed objects).
+
+    # ===================================================================
+    #  :winloop pump (runs on the loop thread; the only winloop-protocol caller)
+    # ===================================================================
+
+    def start_pump(sched)
+      @sched         = sched
+      @loop_thread   = Thread.current
+      @issue_lock    = ::Mutex.new
+      @mutex         = ::Mutex.new
+      @cond          = ::ConditionVariable.new
+      @events        = []
+      @closed        = false
+      @pump_done     = false
+      @first_issue_code = nil
+
+      # Associate our directory handle with the loop's IOCP. The scheduler's
+      # op_associate takes the raw HANDLE Integer; we expose it via a private
+      # primitive so winwatch's struct stays the single owner.
+      sched.op_associate(handle_value)
+
+      # Spawn the pump fiber; winloop's `fiber` hook resumes it immediately to
+      # its first park, so @first_issue_code is set by the time schedule returns.
+      Fiber.schedule { pump_loop }
+
+      # First-issue handoff (§6.1): raise on any nonzero open-time code.
+      code = @first_issue_code
+      return if code.nil? || code.zero?
+
+      _close_handle
+      raise_open_code(code)
+    end
+    private :start_pump
+
+    def handle_value
+      @handle_value ||= _handle_value
+    end
+    private :handle_value
+
+    def pump_loop
+      first = true
+      loop do
+        code = nil
+        op_id = nil
+        @issue_lock.synchronize do
+          if @closed
+            code = :closed
+          else
+            op_id, ov, buf = @sched.op_prepare(handle_value, capacity: @buffer_size)
+            code = _issue(ov, buf, @buffer_size)
+            if code.zero?
+              @sched.op_submitted(op_id)
+            else
+              @sched.op_abandon(op_id)
+            end
+          end
+        end
+        break if code == :closed
+
+        # A successful issue clears the CONSECUTIVE re-issue-failure counter so a
+        # later, unrelated single ERROR_NOTIFY_ENUM_DIR cannot reach the :gone
+        # threshold off a stale count from a long-recovered earlier overflow
+        # (§5.0: "second consecutive failure -> :gone").
+        @issue_retry = 0 if code.zero?
+
+        if first
+          @first_issue_code = code
+          first = false
+          break unless code.zero? # open-time failure: watch raises, pump exits
+        elsif !code.zero?
+          # mid-life issue failure: :rescan retry-once / :gone (§5.0)
+          break if classify_issue_failure(code)
+
+          next # retry the issue
+        end
+
+        bytes, err, data = @sched.await_op(op_id) # parks OUTSIDE the lock; NO timeout
+        break unless handle_completion(bytes, err, data)
+      end
+    ensure
+      signal_pump_done
+    end
+    private :pump_loop
+
+    # Map a completion (bytes, error, data) to events on the @events queue.
+    # Returns true to keep pumping, false to stop (terminal / closed).
+    def handle_completion(bytes, err, data)
+      return false if @closed
+
+      events = classify(data, err.to_i, 0)
+      enqueue(events) unless events.empty?
+      if events.any? { |e| e.type == :gone }
+        # Terminal: auto-close so the next drained take raises Closed (§2.5).
+        # The :gone event is already queued for delivery; mark closed and close
+        # the handle (the op already completed terminally — nothing to cancel).
+        @closed = true
+        _mark_closed
+        _close_handle
+        return false
+      end
+      true
+    end
+    private :handle_completion
+
+    # Mid-life re-issue failure classification (returns true to STOP the pump).
+    def classify_issue_failure(code)
+      if code == Winwatch::ERROR_NOTIFY_ENUM_DIR
+        @issue_retry = (@issue_retry || 0) + 1
+        enqueue([Event.new(:rescan, @path, nil, nil).freeze])
+        return true if @issue_retry >= 2 # second consecutive failure -> :gone
+
+        false # retry the issue once
+      else
+        enqueue([Event.new(:gone, @path, nil, code).freeze])
+        @closed = true
+        true
+      end
+    end
+    private :classify_issue_failure
+
+    def enqueue(events)
+      @mutex.synchronize do
+        @events.concat(events)
+        @cond.broadcast
+      end
+    end
+    private :enqueue
+
+    def signal_consumers
+      @mutex.synchronize { @cond.broadcast }
+    end
+    private :signal_consumers
+
+    def signal_pump_done
+      @mutex.synchronize do
+        @pump_done = true
+        @cond.broadcast
+      end
+    end
+    private :signal_pump_done
+
+    # The pump is dead when its done flag is unset AND the loop is gone. Primary
+    # signal: the recorded loop thread is no longer alive (Winloop.run unwound
+    # and its thread finished). winloop's #closed? is NOT usable for this —
+    # under Winloop.run, #close IS the loop, so @sched.closed? is true for the
+    # whole run after the first park (it would falsely report every parked
+    # consumer's pump dead). So detection degrades to loop-thread liveness alone
+    # (§6.1 / open-risk 1: weaker, but correct for the worker-thread loop the
+    # tests and real callers use). As a secondary signal we still consult
+    # closed? ONLY when the loop thread is the current thread is false — i.e. we
+    # are NOT being driven by the loop right now and a closed scheduler then
+    # really means the loop is over.
+    def pump_dead?
+      return false if @pump_done
+      return true unless @loop_thread.alive?
+      return false if Thread.current.equal?(@loop_thread)
+
+      @sched.respond_to?(:closed?) && @sched.closed?
+    end
+    private :pump_dead?
+
+    def wait_for_pump_done
+      @mutex.synchronize do
+        loop do
+          return if @pump_done
+
+          if pump_dead?
+            # Loop already gone; the pump can never signal. Close directly.
+            _close_handle
+            @pump_done = true
+            return
+          end
+          @cond.wait(@mutex, 0.05)
+        end
+      end
+    end
+    private :wait_for_pump_done
+
+    # ===================================================================
+    #  Completion classification + event construction (one table, both modes)
+    # ===================================================================
+
+    # Map one (data, code, rearm_code) completion to an Array<Event> (§5.0).
+    # data is a binary String (raw batch) or nil; code is the completion's Win32
+    # code; rearm_code is the standalone re-arm result (0 in :winloop, handled by
+    # the pump). An empty Array means "no event; re-armed; keep waiting".
+    def classify(data, code, rearm_code)
+      if code.zero?
+        if data && !data.empty?
+          events = parse_to_events(data)
+          # A re-arm failure after a good batch is terminal: append :gone.
+          append_rearm_failure(events, rearm_code)
+          events
+        else
+          # zero-byte successful completion = overflow (success spelling)
+          rescan_then_rearm(rearm_code)
+        end
+      elsif code == Winwatch::ERROR_NOTIFY_ENUM_DIR
+        rescan_then_rearm(rearm_code)
+      elsif code == Winwatch::ERROR_OPERATION_ABORTED
+        # a cancel: ours (close) or thread rundown (§5.11)
+        return [] if closed? # silent shutdown (close will raise Closed)
+
+        # thread-rundown 995: no event of its own, BUT the re-arm that follows
+        # the cancel can still fail (root deleted / network dropped between the
+        # cancel and the re-issue). Honor rearm_code exactly as the data/1022
+        # branches do, so a permanently un-armed op becomes a terminal :gone
+        # (or a recoverable :rescan for 1022) instead of an infinite re-loop.
+        append_rearm_failure([], rearm_code) # [] unless the re-arm really failed
+      elsif code == Winwatch::ERROR_NOTIFY_CLEANUP
+        # our own handle close completed the op; silent shutdown unless a re-arm
+        # we attempted afterward failed for real (same rationale as 995).
+        append_rearm_failure([], rearm_code)
+      else
+        # 5 (delete-pending), 64, 56, 1450, ... watch died -> :gone + auto-close
+        [Event.new(:gone, @path, nil, code).freeze]
+      end
+    end
+    private :classify
+
+    def rescan_then_rearm(rearm_code)
+      events = [Event.new(:rescan, @path, nil, nil).freeze]
+      append_rearm_failure(events, rearm_code)
+      events
+    end
+    private :rescan_then_rearm
+
+    # A nonzero standalone re-arm code after we already produced events is
+    # terminal (the watch can no longer continue): append :gone (unless the
+    # re-arm failed only because the op was cancelled by us / a rundown). Always
+    # returns +events+ so callers can both mutate-and-return in one step (the 995
+    # / 745 branches pass a fresh []).
+    def append_rearm_failure(events, rearm_code)
+      return events if rearm_code.nil? || rearm_code.zero?
+      return events if rearm_code == Winwatch::ERROR_OPERATION_ABORTED
+
+      if rearm_code == Winwatch::ERROR_NOTIFY_ENUM_DIR
+        # re-arm hit overflow: surface a :rescan, the next take re-arms again
+        events << Event.new(:rescan, @path, nil, nil).freeze
+      else
+        events << Event.new(:gone, @path, nil, rearm_code).freeze
+      end
+      events
+    end
+    private :append_rearm_failure
+
+    # Turn parsed [action, name] records into events, with rename pairing
+    # (adjacent-only, never withholds; §5.8). A malformed-chain sentinel
+    # (ACTION_RESCAN) becomes a trailing :rescan.
+    def parse_to_events(data)
+      records = Winwatch._parse(data)
+      events  = []
+      i = 0
+      while i < records.length
+        action, name = records[i]
+        case action
+        when Winwatch::ACTION_ADDED
+          events << make_event(:added, name)
+        when Winwatch::ACTION_REMOVED
+          events << make_event(:removed, name)
+        when Winwatch::ACTION_MODIFIED
+          events << make_event(:modified, name)
+        when Winwatch::ACTION_RENAMED_OLD_NAME
+          nxt = records[i + 1]
+          if nxt && nxt[0] == Winwatch::ACTION_RENAMED_NEW_NAME
+            events << make_rename(name, nxt[1])
+            i += 1 # consumed the NEW too
+          else
+            # OLD with no immediately-following NEW degrades to :removed (§5.8)
+            events << make_event(:removed, name)
+          end
+        when Winwatch::ACTION_RENAMED_NEW_NAME
+          # NEW with no immediately-preceding OLD degrades to :added (§5.8)
+          events << make_event(:added, name)
+        when Winwatch::ACTION_RESCAN
+          events << Event.new(:rescan, @path, nil, nil).freeze
+        end
+        i += 1
+      end
+      events
+    end
+    private :parse_to_events
+
+    def make_event(type, rel_name)
+      Event.new(type, join_path(rel_name), nil, nil).freeze
+    end
+    private :make_event
+
+    def make_rename(old_rel, new_rel)
+      Event.new(:renamed, join_path(new_rel), join_path(old_rel), nil).freeze
+    end
+    private :make_rename
+
+    # Join the watch root with a record's relative name: translate '\' -> '/',
+    # best-effort 8.3 normalization when normalize_names and a component has '~'.
+    def join_path(rel_name)
+      rel = rel_name.tr("\\", "/")
+      abs = "#{@path}/#{rel}"
+      abs = normalize_short(abs) if @normalize && rel_name.include?("~")
+      abs.freeze
+    end
+    private :join_path
+
+    def normalize_short(abs)
+      long = Winwatch._long_path(abs.tr("/", "\\"))
+      return abs if long.nil?
+
+      long.tr("\\", "/")
+    end
+    private :normalize_short
+
+    def raise_open_code(code)
+      case code
+      when 1       then raise Unsupported.new_with_code("ReadDirectoryChangesW", code)
+      when 2, 3    then raise NotFound.new_with_code("ReadDirectoryChangesW", code)
+      when 5       then raise AccessDenied.new_with_code("ReadDirectoryChangesW", code)
+      else              raise OSError.new_with_code("ReadDirectoryChangesW", code)
+      end
+    end
+    private :raise_open_code
+  end
+
+  # OSError subclasses get a tiny ctor so the :winloop first-issue handoff can
+  # raise the same shape the C open path would (message + @code).
+  class OSError
+    def self.new_with_code(api, code)
+      exc = new("#{api} failed (error #{code})")
+      exc.instance_variable_set(:@code, code)
+      exc
+    end
+  end
+end