woods 2.0.0.beta1 → 2.0.0.beta3

data/lib/woods/agent_configuration/plan_diff.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'tempfile'
+require 'open3'
+require_relative 'plan'
+
+module Woods
+  module AgentConfiguration
+    module PlanDiff
+      def self.show(plan, output)
+        plan.data.fetch('changes').each do |change|
+          document = Document.new(change.fetch('path'))
+          unless document.fingerprint == change.fetch('before')
+            raise Conflict, "Changed since preview: #{document.path}; create a new plan before viewing its diff"
+          end
+
+          output.write(render(document, Plan.after_content(change)))
+        end
+      end
+
+      def self.render(document, content)
+        Tempfile.create('woods-config-before') do |before|
+          Tempfile.create('woods-config-after') do |after|
+            before.write(document.content.to_s)
+            after.write(content.to_s)
+            before.flush
+            after.flush
+            diff, status = Open3.capture2('diff', '-u', '--label', document.path, '--label', document.path,
+                                          before.path, after.path)
+            raise Conflict, 'Cannot render plan diff' unless [0, 1].include?(status.exitstatus)
+
+            diff
+          end
+        end
+      end
+    end
+  end
+end

data/lib/woods/agent_configuration/planned_files.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Woods
+  module AgentConfiguration
+    # Compute exact document replacements while tracking receipt-owned files.
+    module PlannedFiles
+      private
+
+      def prepare_config
+        document = Document.new(@layout.config_path)
+        value = document.json
+        servers = value.fetch('mcpServers', {})
+        raise Conflict, "mcpServers must be an object: #{document.path}" unless servers.is_a?(Hash)
+
+        validate_server_ownership!(servers)
+        @created_files = @previous ? @previous.fetch('created_files').dup : []
+        track_created_file(document)
+        if @operation == 'remove'
+          servers.delete(@name)
+        else
+          servers[@name] = @entry
+        end
+        value['mcpServers'] = servers
+        @plan.add(document, config_content(document, value),
+                  description: "#{@operation} owned Index MCP entry #{@name}")
+      end
+
+      def config_content(document, value)
+        return if @operation == 'remove' && @created_files.include?(document.path) && value == { 'mcpServers' => {} }
+
+        document.encode_json(value)
+      end
+
+      def prepare_sections
+        previous_sections = @previous ? @previous.fetch('sections') : {}
+        requested = @instructions || previous_sections.keys
+        requested = [] if @operation == 'remove'
+        validate_instruction_selection!(requested, previous_sections)
+        @sections = {}
+        (previous_sections.keys | requested).each do |name|
+          prepare_section(name, previous_sections[name], removing: !requested.include?(name))
+        end
+      end
+
+      def prepare_section(name, previous, removing:)
+        document = Document.new(@layout.instruction_path(name))
+        content, ownership = ManagedSection.change(document.content, previous: previous, remove: removing)
+        track_created_file(document)
+        content = nil if removing && content == '' && @created_files.include?(document.path)
+        @sections[name] = ownership if ownership
+        @plan.add(document, content, description: "#{removing ? 'remove' : 'write'} owned Woods instruction section")
+      end
+
+      def track_created_file(document)
+        return unless document.content.nil? && !@created_files.include?(document.path)
+
+        @created_files << document.path
+      end
+    end
+  end
+end

data/lib/woods/agent_configuration/planner.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative 'plan'
+require_relative 'managed_section'
+require_relative 'planner_validation'
+require_relative 'planned_files'
+
+module Woods
+  module AgentConfiguration
+    class Planner
+      include PlannerValidation
+      include PlannedFiles
+
+      TEMPLATE_VERSION = 1
+
+      def initialize(layout:, operation:, entry: nil, **options)
+        unknown = options.keys - %i[name instructions evidence intent]
+        raise ArgumentError, "unknown keywords: #{unknown.join(', ')}" unless unknown.empty?
+
+        name = options.fetch(:name, 'woods')
+        raise Conflict, 'Supported operations: setup, update, remove' unless %w[setup update remove].include?(operation)
+        raise Conflict, 'Server name must be a simple nonempty name' unless name.match?(/\A[a-zA-Z0-9_-]+\z/)
+
+        @layout = layout
+        @operation = operation
+        @entry = entry
+        @name = name
+        @instructions = options[:instructions]
+        @evidence = options.fetch(:evidence, {})
+        @intent = options.fetch(:intent, {})
+      end
+
+      def call
+        @receipt_document = Document.new(@layout.receipt_path)
+        @previous = @receipt_document.content && @receipt_document.json
+        validate_receipt!
+        @plan = Plan.new(layout: @layout, operation: @operation, evidence: @evidence)
+        return @plan if @operation == 'remove' && @previous.nil?
+
+        prepare_config
+        prepare_sections
+        prepare_receipt
+        @plan
+      end
+
+      private
+
+      def prepare_receipt
+        if @operation == 'remove'
+          @plan.add(@receipt_document, nil, description: 'remove installation receipt')
+          return
+        end
+        receipt = { 'schema_version' => 1, 'template_version' => TEMPLATE_VERSION, 'layout' => @layout.identity,
+                    'server_name' => @name, 'entry' => @entry, 'sections' => @sections,
+                    'created_files' => @created_files, 'intent' => @intent, 'evidence' => @evidence }
+        # A repeated setup never silently upgrades the installation's template
+        # or evidence version. The explicit update operation owns that change.
+        receipt = @previous if @operation == 'setup' && @previous && @plan.data.fetch('changes').empty?
+        @plan.add(@receipt_document, @receipt_document.encode_json(receipt), description: 'record owned installation')
+      end
+    end
+  end
+end

data/lib/woods/agent_configuration/planner_validation.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Woods
+  module AgentConfiguration
+    # Receipt and command validation shared by the planner's file preparations.
+    module PlannerValidation
+      private
+
+      def validate_receipt!
+        if @previous
+          validate_receipt_identity!
+        elsif @operation == 'update'
+          raise Conflict, 'No owned installation to update; run setup first'
+        end
+        return if @operation == 'remove'
+
+        validate_entry!
+        validate_setup_compatibility! if @operation == 'setup' && @previous
+      end
+
+      def validate_receipt_identity!
+        valid = @previous['schema_version'] == 1 && @previous['layout'] == @layout.identity &&
+                @previous['server_name'] == @name && @previous['sections'].is_a?(Hash) &&
+                @previous['created_files'].is_a?(Array)
+        raise Conflict, 'Installation receipt does not match this application/client/scope/server' unless valid
+
+        validate_receipt_content!
+      end
+
+      def validate_receipt_content!
+        sections = @previous.fetch('sections')
+        valid_sections = sections.values.all? do |section|
+          section.is_a?(Hash) && section['owned_text'].is_a?(String) && section['prefix'].is_a?(String)
+        end
+        valid_files = (@previous.fetch('created_files') - @layout.allowed_paths).empty?
+        return if valid_sections && valid_files && @previous['entry'].is_a?(Hash)
+
+        raise Conflict, 'Malformed ownership receipt; restore it before updating or removing configuration'
+      end
+
+      def validate_entry!
+        return if @entry.is_a?(Hash) && @entry['command'].is_a?(String) && @entry['args'].is_a?(Array)
+
+        raise Conflict, 'A preflight-validated Index MCP command is required'
+      end
+
+      def validate_setup_compatibility!
+        if @previous['entry'] != @entry
+          raise Conflict, 'Setup differs from the owned installation; preview an explicit update'
+        end
+        return if @previous['template_version'] == self.class::TEMPLATE_VERSION
+
+        raise Conflict, 'The instruction template changed; preview an explicit update'
+      end
+
+      def validate_server_ownership!(servers)
+        if @previous
+          return if servers[@name] == @previous.fetch('entry')
+
+          raise Conflict, 'The owned MCP entry was edited or removed; restore it or resolve ownership manually'
+        end
+        return unless servers.key?(@name)
+
+        raise Conflict, "MCP entry #{@name.inspect} already exists without a Woods receipt; choose another name"
+      end
+
+      def validate_instruction_selection!(requested, previous_sections)
+        unless requested.is_a?(Array) && requested.uniq == requested
+          raise Conflict, 'Instruction files must be a unique list'
+        end
+        return unless @operation == 'setup' && @previous && requested.sort != previous_sections.keys.sort
+
+        raise Conflict, 'Instruction selection differs; preview an explicit update'
+      end
+    end
+  end
+end

data/lib/woods/agent_configuration/preflight.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'open3'
+require 'timeout'
+require 'bundler'
+require_relative 'error'
+
+module Woods
+  module AgentConfiguration
+    class Preflight
+      REQUIRED_TOOLS = %w[woods_status search lookup dependencies dependents].freeze
+      SCRIPT = <<~'RUBY'
+        require 'timeout'
+        Timeout.timeout(25) do
+          require 'json'
+          require 'woods'
+          require 'woods/mcp/server'
+          require 'woods/resilience/index_validator'
+          root = File.realpath(ARGV.fetch(1))
+          index = File.realpath(ARGV.fetch(0))
+          spec = Gem.loaded_specs.fetch('woods')
+          abort 'Installed Woods is missing woods-mcp-start' unless spec.executables.include?('woods-mcp-start')
+          reader = Woods::MCP::IndexReader.new(index)
+          manifest = reader.manifest
+          abort 'Published extraction manifest missing or malformed' unless manifest.is_a?(Hash) && manifest['counts'].is_a?(Hash)
+          report = Woods::Resilience::IndexValidator.new(index_dir: index, app_root: root).validate
+          abort report.errors.join("\n") unless report.valid?
+          tools = Woods::MCP::Server.build(index_dir: index, warmup: false).tools.keys
+          puts JSON.generate(version: Woods::VERSION, tools: tools.sort, root: root, index: index,
+                             generation: reader.loaded_generation, warnings: report.warnings)
+        end
+      RUBY
+
+      def initialize(timeout: 30)
+        @timeout = timeout
+      end
+
+      def call(launcher)
+        output = run(launcher)
+        evidence = JSON.parse(output)
+        raise Conflict, 'Installed Woods preflight expected a JSON object' unless evidence.is_a?(Hash)
+
+        missing = REQUIRED_TOOLS - Array(evidence['tools'])
+        raise Conflict, "Installed Woods lacks required Index capabilities: #{missing.join(', ')}" unless missing.empty?
+        raise Conflict, 'Installed Woods did not report its version' unless evidence['version'].is_a?(String)
+
+        evidence
+      rescue JSON::ParserError
+        raise Conflict, 'Installed Woods preflight did not return valid JSON; inspect application bundle and index'
+      end
+
+      private
+
+      def run(launcher)
+        command = launcher.probe_command(SCRIPT)
+        environment = Bundler.unbundled_env.merge(launcher.probe_environment)
+        Open3.popen3(environment, *command, chdir: launcher.root, unsetenv_others: true,
+                                            pgroup: true) do |stdin, out, err, wait|
+          stdin.close
+          collect(out, err, wait)
+        end
+      rescue Errno::ENOENT => e
+        raise Conflict, "Launch command unavailable: #{e.message}"
+      end
+
+      def collect(stdout, stderr, wait)
+        readers = [stdout, stderr].map { |stream| Thread.new { bounded_read(stream) } }
+        Timeout.timeout(@timeout) do
+          output, errors = readers.map(&:value)
+          raise Conflict, "Installed Woods preflight failed: #{errors.strip}" unless wait.value.success?
+
+          output
+        end
+      rescue Timeout::Error
+        raise Conflict, "Installed Woods preflight exceeded #{@timeout}s; verify the selected command and container"
+      ensure
+        terminate(wait.pid)
+        readers&.each(&:kill)
+      end
+
+      def bounded_read(stream)
+        output = String.new
+        loop do
+          chunk = stream.readpartial(16_384)
+          output << chunk
+          raise Conflict, 'Installed Woods preflight output exceeded 1 MiB' if output.bytesize > 1_048_576
+        end
+      rescue EOFError
+        output
+      end
+
+      def terminate(pid)
+        Process.kill('KILL', -pid)
+      rescue Errno::ESRCH
+        nil
+      end
+    end
+  end
+end

data/lib/woods/agent_configuration/recovery.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Woods
+  module AgentConfiguration
+    # Validate every journal snapshot before restoring any managed file.
+    module Recovery
+      private
+
+      def recover_journal(journal)
+        plan = Plan.allocate
+        plan.instance_variable_set(:@data, journal.fetch('plan'))
+        plan.validate!(@layout)
+        changes = plan.data.fetch('changes')
+        originals = journal.fetch('originals')
+        validate_originals!(originals, changes)
+        changes.each { |change| validate_recovery_snapshot!(change) }
+        originals.zip(changes).reverse_each { |original, change| restore_original(original, change) }
+        File.unlink(journal_path)
+      rescue KeyError, TypeError, ArgumentError => e
+        raise Conflict, "Invalid recovery journal; retained for manual recovery: #{e.message}"
+      end
+
+      def validate_originals!(originals, changes)
+        paths = changes.map { |entry| entry['path'] }
+        return if originals.is_a?(Array) && originals.all?(Hash) && originals.map { |entry| entry['path'] } == paths
+
+        raise Conflict, "Invalid recovery journal; retain it for manual recovery: #{journal_path}"
+      end
+
+      def validate_recovery_snapshot!(change)
+        return if [change.fetch('before'), Plan.after_fingerprint(change)].include?(current(change))
+
+        raise Conflict,
+              "Concurrent edit prevents recovery of #{change.fetch('path')}; journal retained: #{journal_path}"
+      end
+
+      def restore_original(original, change)
+        return if current(change) == change.fetch('before')
+
+        content = original['content'] && Base64.strict_decode64(original['content']).force_encoding(Encoding::UTF_8)
+        expected = { 'sha256' => content && Digest::SHA256.hexdigest(content),
+                     'mode' => original.fetch('mode'), 'exists' => !content.nil? }
+        assert_snapshot!(expected, change.fetch('before'), original.fetch('path'))
+        assert_snapshot!(current(change), Plan.after_fingerprint(change), original.fetch('path'))
+        replace(original.fetch('path'), content, original.fetch('mode'))
+      end
+    end
+  end
+end

data/lib/woods/ast/node.rb

@@ -26,6 +26,8 @@ module Woods
       :arguments,   # Array<String>: argument representations (for :send)
       :source,      # String | nil: raw source text of this node
       :end_line,    # Integer | nil: 1-based end line number (when available)
+      :start_byte,   # Integer | nil: inclusive byte offset into the parsed source
+      :end_byte,     # Integer | nil: exclusive byte offset into the parsed source
       keyword_init: true
     ) do
       # Find all descendant nodes matching a type.

data/lib/woods/ast/parser.rb

@@ -32,6 +32,21 @@ module Woods
         raise Woods::ExtractionError, "Failed to parse source: #{e.message}"
       end
 
+      # Validate a candidate excerpt without logging expected syntax failures
+      # (for example a heredoc body outside a method's syntactic AST range).
+      # The parser instance owns its diagnostics; no global stderr redirection.
+      def valid_fragment?(source)
+        return Prism.parse(source).success? if prism_available?
+
+        require 'parser/current' unless defined?(::Parser::CurrentRuby)
+        parser = ::Parser::CurrentRuby.default_parser
+        parser.diagnostics.consumer = nil
+        buffer = ::Parser::Source::Buffer.new('(fragment)', source: source)
+        !parser.parse(buffer).nil?
+      rescue StandardError
+        false
+      end
+
       # Check if Prism is available.
       #
       # @return [Boolean]
@@ -262,7 +277,9 @@ module Woods
           end_line: end_line_for_prism(prism_node),
           method_name: prism_node.name.to_s,
           receiver: receiver_text,
-          source: extract_prism_source_span(prism_node, source)
+          source: extract_prism_source_span(prism_node, source),
+          start_byte: prism_node.location.start_offset,
+          end_byte: prism_node.location.end_offset
         )
       end
 
@@ -524,12 +541,16 @@ module Woods
             line: parser_node.loc.line,
             end_line: parser_node.loc.expression.last_line,
             method_name: parser_node.children[0].to_s,
-            source: extract_parser_source_span(parser_node, source)
+            source: extract_parser_source_span(parser_node, source),
+            start_byte: original_byte_offset(source, parser_node.loc.expression.line,
+                                             parser_node.loc.expression.column),
+            end_byte: original_byte_offset(source, parser_node.loc.expression.last_line,
+                                           parser_node.loc.expression.last_column)
           )
         when :defs
           body = parser_node.children[3] ? convert_parser_node(parser_node.children[3], source) : nil
           body_children = parser_body_children(body)
-          receiver = parser_node.children[0].type == :self ? 'self' : parser_node.children[0].to_s
+          receiver = extract_parser_receiver_text(parser_node.children[0], source)
           Node.new(
             type: :defs,
             children: body_children,
@@ -537,7 +558,11 @@ module Woods
             end_line: parser_node.loc.expression.last_line,
             method_name: parser_node.children[1].to_s,
             receiver: receiver,
-            source: extract_parser_source_span(parser_node, source)
+            source: extract_parser_source_span(parser_node, source),
+            start_byte: original_byte_offset(source, parser_node.loc.expression.line,
+                                             parser_node.loc.expression.column),
+            end_byte: original_byte_offset(source, parser_node.loc.expression.last_line,
+                                           parser_node.loc.expression.last_column)
           )
         when :send
           receiver_text = parser_node.children[0] ? extract_parser_receiver_text(parser_node.children[0], source) : nil
@@ -611,8 +636,16 @@ module Woods
         end
       end
 
+      # parser gem normalizes CRLF in its source buffer. Its line/character
+      # columns still identify the original source, but absolute positions do
+      # not. Map through original lines to preserve both CRLF and Unicode bytes.
+      def original_byte_offset(source, line, column)
+        lines = source.lines
+        lines.take(line - 1).sum(&:bytesize) + lines.fetch(line - 1)[0, column].bytesize
+      end
+
       def parser_body_children(body_node)
-        body_node&.type == :begin ? body_node.children : [body_node].compact
+        body_node.is_a?(Node) && body_node.type == :begin ? body_node.children : [body_node].compact
       end
 
       def extract_parser_source_span(node, source)

data/lib/woods/atomic_file.rb

@@ -25,11 +25,30 @@ module Woods
     # one: the watch daemon's +watch_status.json+, read by host-side hooks
     # through a bind mount).
     #
+    # +durable:+ chooses when the bytes are forced to the disk, never whether
+    # the write is atomic. Both paths go tempfile, chmod, rename, so a reader
+    # sees the old content or the new content and never a torn partial.
+    # +durable: false+ drops the two forced flushes (the temp file's own
+    # +fsync+ and the containing directory's), which is the whole cost of the
+    # write on a journalling filesystem: roughly 8.9ms per file against
+    # 0.11ms without, measured on btrfs.
+    #
+    # It is only safe for a file with no reader until something else commits
+    # it. Woods' payload files qualify: every reader resolves through
+    # +generation.json+, and that pointer is written durably after
+    # {.sync_directory_tree} has flushed the payload it names. A file whose
+    # readers do not go through the pointer (the watch daemon's status, the
+    # update check's cache, an export, an embedding checkpoint) must stay
+    # durable.
+    #
     # @param path [String, Pathname] destination path
     # @param content [String] file content
     # @param mode [Integer] permissions for the written file (default 0600)
+    # @param durable [Boolean] force the bytes to disk before returning
+    #   (default true). Pass false only for a file that something else makes
+    #   durable before any reader can resolve it.
     # @return [void]
-    def write(path, content, mode: 0o600)
+    def write(path, content, mode: 0o600, durable: true)
       path = path.to_s
       FileUtils.mkdir_p(File.dirname(path))
       tmp = Tempfile.new('.woods-', File.dirname(path))
@@ -38,19 +57,130 @@ module Woods
       tmp.binmode
       tmp.write(content)
       tmp.flush
-      tmp.fsync
+      tmp.fsync if durable
       tmp.close
       # Chmod the temp file so the destination is born with its final
       # permissions — never observed more open or more closed in between.
       File.chmod(mode, tmp.path)
       File.rename(tmp.path, path)
-      fsync_directory(File.dirname(path))
+      fsync_directory(File.dirname(path)) if durable
     rescue StandardError
       tmp&.close
       tmp&.unlink
       raise
     end
 
+    # Make every file under +directory+ durable with one filesystem flush.
+    #
+    # The counterpart to {.write}'s +durable: false+. Thousands of per-file
+    # +fsync+ calls and one +syncfs+ buy the same guarantee for a payload that
+    # is published all at once, and cost 71.3s against 1.0s for 8000 files on
+    # btrfs.
+    #
+    # Strategies, in order, first one that works wins:
+    #
+    # 1. +syncfs(2)+ on a descriptor for +directory+, through Fiddle. Linux
+    #    only, and flushes exactly the one filesystem the payload is on.
+    # 2. +sync -f <dir>+ (GNU coreutils), the same call through a subprocess.
+    # 3. +sync+ with no arguments (BSD/macOS), which flushes everything
+    #    mounted rather than one filesystem, but is still one call.
+    # 4. an +fsync+ on every file and directory in the tree.
+    #
+    # The last resort is what keeps the guarantee honest: the chain never
+    # silently does nothing, it only ever gets slower.
+    #
+    # Fiddle is a default gem through Ruby 3.4 and a bundled gem from 3.5, so
+    # the require lives inside a rescue and Fiddle is deliberately not in the
+    # gemspec. A host without it lands on +sync -f+.
+    #
+    # @param directory [String, Pathname] the tree to flush
+    # @return [Symbol, nil] the strategy that ran (+:syncfs+, +:sync_f+,
+    #   +:sync+, +:fsync_pass+), or nil when the directory does not exist
+    def sync_directory_tree(directory)
+      directory = directory.to_s
+      return nil unless File.directory?(directory)
+
+      strategy = syncfs(directory) || sync_f(directory) || plain_sync || fsync_pass(directory)
+      log_sync_strategy(strategy, directory)
+      strategy
+    end
+
+    # @return [Symbol, nil] +:syncfs+ when the libc call succeeded
+    def syncfs(directory)
+      call = syncfs_function
+      return nil unless call
+
+      succeeded = File.open(directory, File::RDONLY) { |dir| call.call(dir.fileno).zero? }
+      succeeded ? :syncfs : nil
+    rescue StandardError
+      nil
+    end
+
+    # Resolved once per process, and nil for the whole process when it cannot
+    # be. `dlopen` is not free, and a failed `require 'fiddle'` prints a
+    # bundled-gem warning on every attempt from Ruby 3.5 onward, and a publish
+    # must not emit one line of noise per generation.
+    #
+    # @return [Fiddle::Function, nil]
+    def syncfs_function
+      return @syncfs_function if defined?(@syncfs_function)
+
+      @syncfs_function = begin
+        require 'fiddle'
+        Fiddle::Function.new(Fiddle.dlopen(nil)['syncfs'], [Fiddle::TYPE_INT], Fiddle::TYPE_INT)
+      rescue LoadError, StandardError
+        # No Fiddle in the bundle, no libc symbol (macOS has none), or the
+        # handle would not open. `sync -f` is next in the chain.
+        nil
+      end
+    end
+
+    # @return [Symbol, nil] +:sync_f+ when `sync -f` exited 0
+    def sync_f(directory)
+      :sync_f if system('sync', '-f', directory, out: File::NULL, err: File::NULL)
+    rescue StandardError
+      nil
+    end
+
+    # @return [Symbol, nil] +:sync+ when a bare `sync` exited 0
+    def plain_sync
+      :sync if system('sync', out: File::NULL, err: File::NULL)
+    rescue StandardError
+      nil
+    end
+
+    # @return [Symbol] always +:fsync_pass+; this is the floor of the chain
+    def fsync_pass(directory)
+      Dir.glob(File.join(directory, '**', '*'), File::FNM_DOTMATCH).each do |entry|
+        next if %w[. ..].include?(File.basename(entry))
+
+        fsync_path(entry)
+      end
+      fsync_path(directory)
+      # The directory entry that names this tree lives in the parent, so a
+      # freshly created (or renamed) payload directory is only durable once
+      # the parent is flushed too. The three faster strategies flush a whole
+      # filesystem and cover this for free; only the scoped pass has to say
+      # it.
+      fsync_path(File.dirname(directory))
+      :fsync_pass
+    end
+
+    # @param path [String] file or directory to flush
+    # @return [void]
+    def fsync_path(path)
+      File.open(path, File::RDONLY, &:fsync)
+    rescue Errno::EINVAL, Errno::ENOTSUP, Errno::EISDIR, Errno::ENOENT, Errno::EACCES
+      nil
+    end
+
+    # @return [void]
+    def log_sync_strategy(strategy, directory)
+      return unless defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+
+      Rails.logger.debug { "[Woods] payload sync via #{strategy} on #{directory}" }
+    end
+
     def fsync_directory(directory)
       File.open(directory, File::RDONLY, &:fsync)
     rescue Errno::EINVAL, Errno::ENOTSUP, Errno::EISDIR