woods 2.0.0 → 2.1.0

data/lib/woods/unblocked/uri_migration.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Woods
+  module Unblocked
+    # Resumable, explicitly selected URI replacements. Ordinary branch changes
+    # never enter this path and never retire another branch's ownership scope.
+    class UriMigration
+      # @param manifest [SyncManifest] currently selected target scope
+      # @param client [Client] remote document operations
+      # @param from_ref [String, nil] explicit source branch, or resume pending work
+      # @param replacements [Hash{String => String}] old URI to published target URI
+      def initialize(manifest:, client:, from_ref:, replacements:)
+        @manifest = manifest
+        @client = client
+        return unless from_ref
+
+        moves = manifest.migration_sources(from_ref: from_ref).filter_map do |entry|
+          target = replacements[entry.fetch('old_uri')]
+          next if target == entry.fetch('old_uri')
+
+          entry.merge('new_uri' => target)
+        end
+        manifest.start_migration(from_ref: from_ref, moves: moves)
+      end
+
+      # @return [Array<Hash>] exact pending replacements, suitable for preview
+      def plan
+        @manifest.migration&.fetch('moves') || []
+      end
+
+      # Save successful replacement receipts before deleting any old copies.
+      # This explicit migration set has its own ownership checks; the ordinary
+      # mass-delete ratio does not mistake a one-for-one migration for loss.
+      # @param current_uris [Set<String>] verified current publication membership
+      # @param errors [Array<String>] actionable refusal/failure messages
+      # @return [Integer] old copies removed
+      def cleanup(current_uris:, errors:, replacement_hashes:, remote_documents:, collection_id:)
+        return 0 if plan.empty?
+
+        @manifest.save
+        deleted = 0
+        plan.dup.each do |move|
+          remote = remote_documents[move.fetch('old_uri')]
+          if remote.nil?
+            finish_move(move)
+            next
+          end
+          reason = refusal(move, current_uris, replacement_hashes)
+          target = remote_documents[move['new_uri']]
+          unless target && target['id'] == @manifest.document_id_for(move['new_uri']) &&
+                 target['collectionId'] == collection_id
+            reason ||= 'replacement remote identity is missing or changed'
+          end
+          reason ||= 'source remote identity/collection changed; review before cleanup' unless
+            remote['id'] == move['document_id'] && remote['collectionId'] == collection_id
+          if reason
+            errors << "URI migration incomplete: #{reason} (#{move.fetch('old_uri')})"
+            next
+          end
+          @client.delete_document(document_id: move.fetch('document_id'))
+          deleted += 1
+          finish_move(move)
+        rescue ApiError => e
+          if e.status == 404
+            finish_move(move)
+          else
+            errors << "URI migration cleanup failed: #{e.message}"
+          end
+        rescue StandardError => e
+          errors << "URI migration cleanup incomplete: #{e.class}: #{e.message}"
+          break
+        end
+        @manifest.finish_migration
+        deleted
+      end
+
+      private
+
+      def refusal(move, current_uris, replacement_hashes)
+        unless move['owned'] == true
+          return 'legacy ownership is unverified; review the remote record before manual cleanup'
+        end
+        unless move['document_id'].is_a?(String) && !move['document_id'].empty?
+          return 'source document ID is unresolved'
+        end
+        return 'no unambiguous current replacement' unless current_uris.include?(move['new_uri'])
+
+        expected = replacement_hashes[move['new_uri']]
+        return 'replacement content has not been successfully synchronized' unless
+          expected && @manifest.unchanged?(move['new_uri'], expected)
+
+        target_id = @manifest.document_id_for(move['new_uri'])
+        return 'replacement has no persisted successful document receipt' unless target_id
+        return 'source and replacement document IDs are identical' if target_id == move['document_id']
+
+        nil
+      end
+
+      def finish_move(move)
+        @manifest.complete_move(move)
+        @manifest.save
+      end
+    end
+  end
+end

data/lib/woods/util/host_guard.rb

@@ -2,8 +2,9 @@
 
 module Woods
   module Util
-    # Shared host-header / URL-host canonicalization used by {MCP::OriginGuard}
-    # and the {Storage::VectorStore::Qdrant} URL validator.
+    # Numeric-host checks shared by {MCP::OriginPolicy} and the
+    # {Storage::VectorStore::Qdrant} URL validator. Qdrant also uses the URL
+    # canonicalization helper; HTTP authorities retain SDK matching semantics.
     #
     # Both components need to reject numeric IPv4 notations that `URI` and
     # `getaddrinfo` accept but `IPAddr` does not — hex (`0x7f000001`),

data/lib/woods/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Woods
-  VERSION = '2.0.0'
+  VERSION = '2.1.0'
 end

data/lib/woods/watch/catch_up.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require 'woods/generation'
+require 'woods/source_inputs/manifest'
+require 'woods/source_inputs/scanner'
+require 'woods/watch/tree_scan'
+
+module Woods
+  module Watch
+    # Generation-bound startup evidence. Publication time is too late: an edit
+    # can land after capture, or even after final verification, before the marker.
+    class CatchUp
+      DIRTY_REASONS = %w[source_changed_during_extraction source_changed_during_read].freeze
+
+      def initialize(root:, output_dir:, ignored:)
+        @root = root
+        @output = output_dir
+        @ignored = ignored
+        @generation = Generation.new(output_dir: output_dir)
+        @marker = @generation.current
+        @manifest = read_manifest
+        report_unavailable if @manifest&.unavailable?
+      end
+
+      # A full run records the missing boundary even when incremental discovery
+      # would find no units to change (and therefore publish no new generation).
+      def rebuild?
+        @marker.number.positive? && @manifest.nil?
+      end
+
+      def paths
+        files = TreeScan.files(root: @root, ignored: @ignored)
+        return files unless @manifest
+
+        candidates = files.select { |path| recent?(path) } | dirty_paths
+        return [] if candidates.empty?
+
+        current = current_identities
+        return [] if captured_tree_matches?(current)
+
+        expected = recorded_identities
+        candidates.reject { |path| covered?(path, current, expected) }
+      end
+
+      private
+
+      def report_unavailable
+        evidence = @manifest.data.fetch('unavailable')
+        warn "[Woods] Watch source freshness unavailable: #{evidence.fetch('reason')}; " \
+             "#{evidence.fetch('size_bytes')} bytes; limit #{evidence.fetch('limit_bytes')}. " \
+             'Continuing source-change catch-up without a freshness comparison ledger.'
+      end
+
+      def captured_tree_matches?(current)
+        @manifest.unavailable? && @current_complete &&
+          @manifest.data['capture_sha256'] == SourceInputs::Manifest.capture_digest(current)
+      end
+
+      def covered?(path, current, expected)
+        relative = path.delete_prefix("#{@root}/")
+        identities = expected[relative]
+        identities && current[relative] && identities.all? { |identity| identity == current[relative] }
+      end
+
+      def read_manifest
+        payload = @generation.payload_dir(@marker)
+        return nil if @marker.payload && payload == @generation.root
+
+        manifest = load_manifest(payload)
+        data = manifest.data
+        return nil unless matching_manifest?(data)
+
+        @key = SourceInputs::PrivateKey.new(output_dir: @output)
+        @scopes = SourceInputs::Scopes.new(extra_roots: data.fetch('extra_roots'))
+        return nil unless @key.identifier == data['key_id'] && @scopes.fingerprint == data['rules']
+
+        manifest
+      rescue SourceInputs::Manifest::Invalid, SourceInputs::PrivateKey::Unavailable, SystemCallError, IOError, TypeError
+        nil
+      end
+
+      def matching_manifest?(data)
+        data['root'] == @root && data['generation'] == @marker.number &&
+          data['captured_at'] && data['captured_at'] <= Time.now.to_f
+      end
+
+      def load_manifest(payload)
+        flags = File::RDONLY | File::NONBLOCK
+        flags |= File::NOFOLLOW if defined?(File::NOFOLLOW)
+        File.open(payload.join(SourceInputs::Manifest::FILE_NAME), flags) do |file|
+          unless file.stat.file? && file.stat.size <= SourceInputs::Manifest::MAX_BYTES
+            raise SourceInputs::Manifest::Invalid, 'invalid_source_manifest'
+          end
+
+          SourceInputs::Manifest.parse(file.read(SourceInputs::Manifest::MAX_BYTES + 1))
+        end
+      end
+
+      def recent?(path)
+        # Filesystems may record only whole seconds. Include the entire capture
+        # second; content comparison below prevents unchanged files repeating.
+        File.mtime(path).to_f >= @manifest.data.fetch('captured_at').floor
+      rescue SystemCallError
+        false
+      end
+
+      def dirty_paths
+        @manifest.data.fetch('errors').filter_map do |error|
+          next unless DIRTY_REASONS.include?(error['reason'])
+
+          path = error['path']
+          next unless relative_path?(path)
+
+          File.join(@root, path)
+        end
+      end
+
+      def relative_path?(path)
+        path.is_a?(String) && !path.empty? && !path.start_with?('/') && !path.include?("\0") &&
+          path.split('/', -1).none? { |part| ['', '.', '..'].include?(part) }
+      end
+
+      def recorded_identities
+        @manifest.expanded.each_value.with_object({}) do |paths, result|
+          paths.each { |path, identity| (result[path] ||= []) << identity }
+        end
+      end
+
+      def current_identities
+        snapshot = SourceInputs::Scanner.new(root: @root, output_dir: @output, key: @key, scopes: @scopes).call
+        @current_complete = snapshot['complete']
+        snapshot.fetch('files')
+      rescue SystemCallError, IOError
+        {}
+      end
+    end
+  end
+end

data/lib/woods/watch/claim_lease.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'securerandom'
+
+module Woods
+  module Watch
+    # The daemon, not its launcher, holds this descriptor for its whole run.
+    # Sidecar inodes are permanent: unlinking a locked file defeats flock.
+    class ClaimLease
+      class Unavailable < StandardError; end
+      CLAIM = 'watch_claim.json'
+      MAX_BYTES = 4096
+
+      attr_reader :token
+
+      # @param index [String] existing index directory
+      def initialize(index)
+        @index = File.realpath(index)
+        @token = SecureRandom.hex(32)
+      end
+
+      # @yield while serialized with daemon claim creation and retirement
+      def coordinate
+        lock = open_lock("#{CLAIM}.lock", create: true)
+        yield
+      ensure
+        lock&.close
+      end
+
+      # @param create [Boolean] only a new daemon can create the permanent lease
+      # @return [void]
+      def acquire(create: true)
+        @lease = open_lock("#{CLAIM}.lease", create: create)
+      end
+
+      # @return [Hash] identity bound to this exact locked inode
+      def fields
+        stat = @lease.stat
+        { lease_version: 1, token: token, lease_device: stat.dev, lease_inode: stat.ino }
+      end
+
+      def close
+        @lease&.close
+        @lease = nil
+      end
+
+      # @return [String] bounded regular claim bytes, without following links
+      def snapshot
+        read_claim
+      end
+
+      # Refuse legacy records and re-check the selected claim while holding both
+      # locks. Neither host names nor claim ages authorize this operation.
+      # @param token [String] exact claim token selected by the operator
+      # @return [void]
+      def recover(token:)
+        raise Unavailable, 'claim token must be 64 hexadecimal characters' unless valid_token?(token)
+
+        coordinate do
+          snapshot = read_claim
+          record = validate_claim(snapshot, token)
+          acquire(create: false)
+          verify_lease(record)
+          raise Unavailable, 'claim changed during recovery; inspect its current owner' unless read_claim == snapshot
+
+          File.unlink(File.join(@index, CLAIM))
+        end
+      ensure
+        close
+      end
+
+      private
+
+      # @param name [String] fixed sidecar basename
+      # @param create [Boolean] permit initial creation
+      # @return [File] locked descriptor; never blocks on a live owner
+      def open_lock(name, create:)
+        flags = File::RDWR | File::NONBLOCK
+        flags |= File::CREAT if create
+        flags |= File::NOFOLLOW if defined?(File::NOFOLLOW)
+        path = File.join(@index, name)
+        file = File.open(path, flags, 0o600) # rubocop:disable Style/FileOpen -- descriptor lifetime is ownership
+        verify_regular_path(file, path)
+        unless file.flock(File::LOCK_EX | File::LOCK_NB)
+          label = name.end_with?('.lease') ? 'owner lease is held' : 'claim coordination is busy'
+          raise Unavailable, "#{label}; stop the owner through its supervisor and retry"
+        end
+        verify_regular_path(file, path)
+        file
+      rescue StandardError
+        file&.close
+        raise
+      end
+
+      # @param file [File] opened sidecar
+      # @param path [String] unchanged regular path on disk
+      def verify_regular_path(file, path)
+        opened = file.stat
+        current = File.lstat(path)
+        return if opened.file? && current.file? && [opened.dev, opened.ino] == [current.dev, current.ino]
+
+        raise Unavailable, 'claim sidecar must be an unchanged regular file; do not replace lock files'
+      end
+
+      def read_claim
+        path = File.join(@index, CLAIM)
+        flags = File::RDONLY | File::NONBLOCK
+        flags |= File::NOFOLLOW if defined?(File::NOFOLLOW)
+        File.open(path, flags) do |file|
+          verify_regular_path(file, path)
+          bytes = file.read(MAX_BYTES + 1)
+          raise Unavailable, 'claim exceeds the recovery size limit' if bytes.bytesize > MAX_BYTES
+
+          bytes
+        end
+      end
+
+      def validate_claim(snapshot, token)
+        record = JSON.parse(snapshot)
+        unless valid_record?(record)
+          raise Unavailable, 'legacy or unverifiable claim; use the documented legacy recovery procedure'
+        end
+        unless record['token'] == token
+          raise Unavailable, 'claim token changed; inspect the current owner before retrying'
+        end
+
+        record
+      rescue JSON::ParserError
+        raise Unavailable, 'legacy or unverifiable claim; use the documented legacy recovery procedure'
+      end
+
+      def valid_record?(record)
+        record.is_a?(Hash) && record['lease_version'] == 1 && valid_token?(record['token']) &&
+          record['pid'].is_a?(Integer) && record['pid'].positive? && record['host'].is_a?(String)
+      end
+
+      def verify_lease(record)
+        stat = @lease.stat
+        return if record['lease_device'] == stat.dev && record['lease_inode'] == stat.ino
+
+        raise Unavailable, 'owner lease inode changed; ownership cannot be verified'
+      end
+
+      def valid_token?(value)
+        value.is_a?(String) && value.match?(/\A[a-f0-9]{64}\z/)
+      end
+    end
+  end
+end

data/lib/woods/watch/cli.rb

@@ -2,6 +2,7 @@
 
 require 'optparse'
 require_relative 'supervisor'
+require_relative 'claim_lease'
 
 module Woods
   module Watch
@@ -17,12 +18,13 @@ module Woods
       def run(argv)
         options, command = parse(argv.dup)
         return 0 if @help
+        return recover_claim(options, command) if @recovery_index || @claim_token
 
         validate_platform!
         validate_command!(command, options[:root])
         supervisor = Supervisor.new(command: command, logger: @output, **options)
         with_signals(supervisor) { supervisor.run }
-      rescue OptionParser::ParseError, ArgumentError, SystemCallError => e
+      rescue OptionParser::ParseError, ArgumentError, SystemCallError, ClaimLease::Unavailable => e
         @output.puts("[woods-watch] #{e.message}")
         2
       end
@@ -31,6 +33,7 @@ module Woods
 
       def parse(argv)
         @help = false
+        @recovery_index = @claim_token = nil
         options = { root: Dir.pwd, boot_timeout: 300, shutdown_timeout: 10 }
         parser = OptionParser.new do |flags|
           flags.banner = 'Usage: woods-watch [options] -- [bin/rails woods:watch]'
@@ -43,11 +46,32 @@ module Woods
           flags.on('--shutdown-timeout SECONDS', 'Graceful shutdown limit (default: 10)') do |value|
             options[:shutdown_timeout] = positive_seconds(value)
           end
+          recovery_options(flags)
           flags.on('-h', '--help', 'Show help without booting Rails') { @help = true }
         end
         parser.order!(argv)
         @output.puts(parser) if @help
-        [options, argv.empty? ? ['bin/rails', 'woods:watch'] : argv]
+        [options, argv.empty? && !@recovery_index && !@claim_token ? ['bin/rails', 'woods:watch'] : argv]
+      end
+
+      def recovery_options(flags)
+        flags.on('--recover-claim INDEX', 'Recover an abandoned managed claim; requires --claim-token') do |path|
+          @recovery_index = path
+        end
+        flags.on('--claim-token TOKEN', 'Exact claim token; never overrides a live owner lease') do |token|
+          @claim_token = token
+        end
+      end
+
+      def recover_claim(options, command)
+        unless @recovery_index && @claim_token && command.empty?
+          raise ArgumentError, 'use --recover-claim INDEX --claim-token TOKEN without a child command'
+        end
+
+        index = File.expand_path(@recovery_index, options[:root])
+        ClaimLease.new(index).recover(token: @claim_token)
+        @output.puts("[woods-watch] recovered the selected abandoned claim at #{index}; restart its normal owner")
+        0
       end
 
       def positive_seconds(value)