cohere-transcribe 0.1.2 → 0.1.3

data/lib/cohere/transcribe/hub.rb

@@ -14,12 +14,23 @@ module Cohere
     # clients are reused without copying multi-gigabyte model weights.
     class Hub
       class Error < StandardError; end
-      class ConnectionError < Error; end
+      class TransientError < Error; end
+      class ConnectionError < TransientError; end
       class AuthenticationError < Error; end
       class NotFoundError < Error; end
 
       COMMIT_PATTERN = /\A[0-9a-f]{40}\z/i
+      REF_READ_LIMIT = 41
       DEFAULT_ENDPOINT = "https://huggingface.co"
+      RESOLUTION_MEMO_TTL_SECONDS = 5.0
+      RESOLUTION_MEMO_LIMIT = 64
+      CACHE_MODE_UNSUPPORTED_ERRNOS = %i[EPERM EROFS EOPNOTSUPP ENOTSUP].filter_map do |name|
+        Errno.const_get(name)::Errno if Errno.const_defined?(name)
+      end.freeze
+      ResolutionMemo = Struct.new(:value, :error, :expires_at, keyword_init: true)
+
+      private_constant :REF_READ_LIMIT, :RESOLUTION_MEMO_TTL_SECONDS, :RESOLUTION_MEMO_LIMIT,
+                       :CACHE_MODE_UNSUPPORTED_ERRNOS, :ResolutionMemo
 
       attr_reader :cache_dir, :endpoint
 
@@ -29,7 +40,13 @@ module Cohere
         @endpoint = (endpoint || ENV.fetch("HF_ENDPOINT", DEFAULT_ENDPOINT)).sub(%r{/+\z}, "")
         @endpoint_uri = URI(@endpoint)
         @token = token || ENV["HF_TOKEN"] || cached_token(hf_home)
-        @offline = offline.nil? ? truthy_environment?(ENV.fetch("HF_HUB_OFFLINE", nil)) : !!offline
+        @offline = if offline.nil?
+                     truthy_environment?(ENV.fetch("HF_HUB_OFFLINE", nil))
+                   else
+                     offline != false
+                   end
+        @resolution_guard = Mutex.new
+        @resolution_memo = {}
       end
 
       def offline?
@@ -42,33 +59,22 @@ module Cohere
         validate_revision!(requested)
         return requested.downcase if COMMIT_PATTERN.match?(requested)
 
-        cached = cached_revision(repo_id, requested, filename: filename)
         if offline?
+          cached = cached_revision(repo_id, requested, filename: filename)
           return cached if cached
 
           raise Error,
                 "Hub offline mode has no cached #{filename} snapshot for #{repo_id.inspect} at #{requested.inspect}"
         end
 
-        encoded_repo = repo_id.split("/").map { |part| URI.encode_www_form_component(part) }.join("/")
-        encoded_revision = URI.encode_www_form_component(requested)
         begin
-          response = request(URI("#{endpoint}/api/models/#{encoded_repo}/revision/#{encoded_revision}"))
-        rescue ConnectionError
+          resolve_online_revision(repo_id, requested)
+        rescue TransientError
+          cached = cached_revision(repo_id, requested, filename: filename)
           raise unless cached
 
-          return cached
-        end
-        payload = JSON.parse(response.body)
-        commit = payload["sha"]
-        unless commit.is_a?(String) && COMMIT_PATTERN.match?(commit)
-          raise Error, "Hub returned no immutable commit for #{repo_id.inspect} at #{requested.inspect}"
+          cached
         end
-
-        write_ref(repo_id, requested, commit.downcase)
-        commit.downcase
-      rescue JSON::ParserError => e
-        raise Error, "Invalid Hub response while resolving #{repo_id.inspect}: #{e.message}"
       end
 
       def download(repo_id, filename, revision: nil)
@@ -76,7 +82,10 @@ module Cohere
         commit = resolve_revision(repo_id, revision, filename: filename)
         repository = cache_dir.join(cache_repo_name(repo_id))
         destination = repository.join("snapshots", commit, filename)
-        return destination if safe_cached_file(repository, destination)
+        if (cached = safe_cached_file(repository, destination))
+          normalize_cached_payload(repository, cached)
+          return cached
+        end
 
         prepare_cache_directory!(repository, destination.dirname)
         encoded_repo = repo_id.split("/").map { |part| URI.encode_www_form_component(part) }.join("/")
@@ -84,8 +93,17 @@ module Cohere
         uri = URI("#{endpoint}/#{encoded_repo}/resolve/#{commit}/#{encoded_filename}")
 
         open_download_lock(download_lock_path(destination)) do |lock|
-          raise Error, "Cannot acquire Hub download lock for #{destination}" unless lock.flock(File::LOCK_EX)
-          return destination if safe_cached_file(repository, destination)
+          acquire_download_lock!(lock, download_lock_path(destination), destination)
+
+          verify_cache_lock_identity!(
+            download_lock_path(destination),
+            lock,
+            purpose: "Hub download"
+          )
+          if (cached = safe_cached_file(repository, destination))
+            normalize_cached_payload(repository, cached)
+            return cached
+          end
 
           cleanup_download_temporaries(destination)
           Tempfile.create(
@@ -93,6 +111,7 @@ module Cohere
             destination.dirname.to_s,
             binmode: true
           ) do |temporary|
+            apply_cache_mode_if_supported(temporary, cache_payload_mode(destination.dirname))
             request(uri, stream: temporary)
             temporary.flush
             temporary.fsync
@@ -102,7 +121,7 @@ module Cohere
           sync_directory(destination.dirname)
         end
         destination
-      rescue Errno::EACCES, Errno::ENOSPC, Errno::EROFS => e
+      rescue SystemCallError => e
         raise Error, "Cannot cache #{repo_id}/#{filename}: #{e.message}"
       end
 
@@ -110,16 +129,22 @@ module Cohere
         commit = resolve_revision(repo_id, revision)
         encoded_repo = repo_id.split("/").map { |part| URI.encode_www_form_component(part) }.join("/")
         response = request(URI("#{endpoint}/api/models/#{encoded_repo}/revision/#{commit}"))
-        payload = JSON.parse(response.body)
-        siblings = payload["siblings"]
+        payload = JSON.parse(response.body.to_s)
+        siblings = payload.is_a?(Hash) ? payload["siblings"] : nil
         raise Error, "Hub returned no repository file list for #{repo_id}@#{commit}" unless siblings.is_a?(Array)
 
-        siblings.filter_map do |item|
+        files = siblings.filter_map do |item|
           name = item.is_a?(Hash) ? item["rfilename"] : nil
-          name if name.is_a?(String)
-        end.freeze
+          name if name.is_a?(String) && !name.empty?
+        end
+        if files.empty?
+          detail = siblings.empty? ? "an empty repository file list" : "no valid repository file entries"
+          raise Error, "Hub returned #{detail} for #{repo_id}@#{commit}"
+        end
+
+        files.freeze
       rescue JSON::ParserError => e
-        raise Error, "Invalid Hub response while listing #{repo_id.inspect}: #{e.message}"
+        raise TransientError, "Invalid Hub response while listing #{repo_id.inspect}: #{e.message}"
       end
 
       def snapshot_path(repo_id, commit)
@@ -147,6 +172,77 @@ module Cohere
 
       private
 
+      def resolve_online_revision(repo_id, revision)
+        key = resolution_key(repo_id, revision)
+        memo = @resolution_guard.synchronize do
+          prune_resolution_memo
+          @resolution_memo[key]
+        end
+        return resolution_value(memo.value, memo.error) if memo
+
+        # Concurrent misses deliberately perform independent requests. Each
+        # caller uses the response it fetched; the short memo only avoids
+        # repeated requests that begin after one lookup has completed.
+        value = fetch_online_revision(repo_id, revision)
+        write_ref_best_effort(repo_id, revision, value)
+        @resolution_guard.synchronize { memoize_resolution(key, value, nil) }
+        value
+      rescue TransientError => e
+        memo = @resolution_guard.synchronize do
+          prune_resolution_memo
+          current = @resolution_memo[key]
+          memoize_resolution(key, nil, e) unless current
+          current
+        end
+        return resolution_value(memo.value, memo.error) if memo
+
+        raise
+      end
+
+      def fetch_online_revision(repo_id, revision)
+        encoded_repo = repo_id.split("/").map { |part| URI.encode_www_form_component(part) }.join("/")
+        encoded_revision = URI.encode_www_form_component(revision)
+        response = request(URI("#{endpoint}/api/models/#{encoded_repo}/revision/#{encoded_revision}"))
+        payload = JSON.parse(response.body.to_s)
+        commit = payload.is_a?(Hash) ? payload["sha"] : nil
+        unless commit.is_a?(String) && COMMIT_PATTERN.match?(commit)
+          raise TransientError, "Hub returned no immutable commit for #{repo_id.inspect} at #{revision.inspect}"
+        end
+
+        commit.downcase
+      rescue JSON::ParserError => e
+        raise TransientError, "Invalid Hub response while resolving #{repo_id.inspect}: #{e.message}"
+      end
+
+      def memoize_resolution(key, value, error)
+        @resolution_memo.delete(key)
+        @resolution_memo[key] = ResolutionMemo.new(
+          value: value,
+          error: error,
+          expires_at: monotonic + RESOLUTION_MEMO_TTL_SECONDS
+        )
+        @resolution_memo.shift while @resolution_memo.length > RESOLUTION_MEMO_LIMIT
+      end
+
+      def resolution_value(value, error)
+        raise error if error
+
+        value
+      end
+
+      def prune_resolution_memo
+        now = monotonic
+        @resolution_memo.delete_if { |_key, entry| entry.expires_at <= now }
+      end
+
+      def resolution_key(repo_id, revision)
+        [repo_id.dup.freeze, revision.dup.freeze].freeze
+      end
+
+      def monotonic
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
       def request(uri, stream: nil, redirects: 0)
         raise Error, "Hub offline mode prevents a request to #{uri}" if offline?
         raise Error, "Too many redirects while fetching #{uri}" if redirects > 8
@@ -180,7 +276,7 @@ module Cohere
                 end
                 expected = response_content_length(incoming, uri)
                 if expected && written != expected
-                  raise Error,
+                  raise TransientError,
                         "Hub returned an incomplete response body for #{uri}: " \
                         "received #{written} bytes, expected #{expected}"
                 end
@@ -217,7 +313,16 @@ module Cohere
         location = response["location"]
         raise Error, "Hub redirect from #{base} did not include a location" unless location
 
-        URI.join(base.to_s, location)
+        resolved = URI.join(base.to_s, location)
+        unless resolved.is_a?(URI::HTTP) && resolved.host
+          raise Error, "Hub redirect from #{base} returned an invalid location: #{location.inspect}"
+        end
+
+        resolved
+      rescue URI::Error => e
+        raise Error,
+              "Hub redirect from #{base} returned an invalid location: #{location.inspect}",
+              cause: e
       end
 
       def trusted_authorization_origin?(uri)
@@ -228,7 +333,7 @@ module Cohere
       def raise_http_error!(response, uri)
         detail = begin
           parsed = JSON.parse(response.body.to_s)
-          parsed["error"] || parsed["message"]
+          parsed.is_a?(Hash) ? parsed["error"] || parsed["message"] : nil
         rescue JSON::ParserError
           nil
         end
@@ -237,6 +342,7 @@ module Cohere
         case response.code.to_i
         when 401, 403 then raise AuthenticationError, message
         when 404 then raise NotFoundError, message
+        when 429, 500..599 then raise TransientError, message
         else raise Error, message
         end
       end
@@ -246,7 +352,7 @@ module Cohere
         candidates = []
         ref = revision_path(repository, revision)
         cached_ref = safe_cached_file(repository, ref)
-        candidates << cached_ref.read.strip if cached_ref
+        candidates << read_ref_commit(cached_ref) if cached_ref
         candidates << revision if COMMIT_PATTERN.match?(revision)
         candidates.find do |candidate|
           COMMIT_PATTERN.match?(candidate) &&
@@ -256,23 +362,50 @@ module Cohere
         nil
       end
 
+      def read_ref_commit(path)
+        File.open(path, "rb") do |ref|
+          next if ref.stat.size > REF_READ_LIMIT
+
+          value = ref.read(REF_READ_LIMIT)&.strip
+          next if ref.stat.size > REF_READ_LIMIT
+
+          value if value && COMMIT_PATTERN.match?(value)
+        end
+      rescue SystemCallError
+        nil
+      end
+
+      def write_ref_best_effort(repo_id, revision, commit)
+        write_ref(repo_id, revision, commit)
+      rescue Error, SystemCallError
+        # Hub refs are advisory cache hints. A valid online response remains
+        # usable when a shared or read-only cache cannot publish the hint.
+        commit
+      end
+
       def write_ref(repo_id, revision, commit)
         repository = cache_dir.join(cache_repo_name(repo_id))
         path = revision_path(repository, revision)
-        prepare_cache_directory!(repository, path.dirname)
-        # Resolution can happen concurrently in separate Transcriber facades.
-        # A PID-only temporary name lets those threads truncate or rename the
-        # same file out from under one another. Each writer instead publishes a
-        # complete, durable ref from its own file; every competing value is an
-        # immutable commit, so the final atomic rename remains consistent.
+        prepare_cache_directory!(repository, path.dirname, replaceable_entries: true)
+        current = safe_cached_file(repository, path)
+        if current && read_ref_commit(current) == commit
+          normalize_cached_file_mode(current, cache_payload_mode(current.dirname))
+          return commit
+        end
+
+        # Standard Hub refs contain only the immutable commit. Concurrent
+        # writers may replace one complete hint with another, while Tempfile
+        # and rename ensure readers never observe a partial value.
         Tempfile.create([".cohere-transcribe-ref-", ".tmp"], path.dirname.to_s) do |temporary|
-          temporary.write("#{commit}\n")
+          temporary.write(commit)
+          apply_cache_mode_if_supported(temporary, cache_payload_mode(path.dirname))
           temporary.flush
           temporary.fsync
           temporary.close
           File.rename(temporary.path, path)
         end
         sync_directory(path.dirname)
+        commit
       end
 
       def safe_cached_file(repository, path)
@@ -308,42 +441,170 @@ module Cohere
         pattern = destination.dirname.join("#{download_temporary_prefix(destination)}*.download")
         Dir.glob(pattern.to_s).each do |path|
           File.unlink(path)
-        rescue Errno::ENOENT
+        rescue Errno::ENOENT, Errno::EACCES, Errno::EPERM, Errno::EROFS
           nil
         end
       end
 
-      def open_download_lock(path)
-        flags = File::RDWR | File::CREAT
-        flags |= File::NOFOLLOW if defined?(File::NOFOLLOW)
-        flags |= File::CLOEXEC if defined?(File::CLOEXEC)
-        descriptor = ::IO.sysopen(path.to_s, flags, 0o600)
-        lock = File.new(descriptor, "r+", autoclose: true)
-        descriptor = nil
-        opened = lock.stat
-        current = path.lstat
-        unless opened.file? && !current.symlink? && opened.dev == current.dev && opened.ino == current.ino
-          raise Error, "Hub download lock changed while it was being opened or is not regular: #{path}"
-        end
+      def open_download_lock(path, &)
+        open_cache_lock(path, purpose: "Hub download", &)
+      end
+
+      def open_cache_lock(path, purpose:)
+        path = Pathname(path)
+        desired_mode = cache_lock_mode(path.dirname)
+        lock, access, created = open_cache_lock_handle(path, purpose: purpose, mode: desired_mode)
+        opened = verify_cache_lock_identity!(path, lock, purpose: purpose)
+        owned_writable = access == "r+" && cache_file_owned_by_current_process?(opened)
+        apply_cache_mode_if_supported(lock, desired_mode) if (created || owned_writable) && (opened.mode & 0o777) != desired_mode
 
         yield lock
       rescue Errno::ELOOP, Errno::EISDIR, Errno::ENXIO => e
-        raise Error, "Hub download lock is not a regular file: #{path}", cause: e
+        raise Error, "#{purpose} lock is not a regular file: #{path}", cause: e
       ensure
         lock&.close
+      end
+
+      def open_cache_lock_handle(path, purpose:, mode:)
+        descriptor = nil
+        handle = nil
+        replacement = nil
+        retired = nil
+        succeeded = false
+        begin
+          descriptor, created = open_or_create_cache_lock_descriptor(path, cache_lock_flags, mode)
+          access = "r+"
+        rescue Errno::EACCES, Errno::EROFS => e
+          descriptor = open_readonly_cache_lock_descriptor(path, purpose: purpose, write_error: e)
+          created = false
+          access = "r"
+        end
+
+        handle = File.new(descriptor, access, autoclose: true)
+        descriptor = nil
+        opened = verify_cache_lock_identity!(path, handle, purpose: purpose)
+        if access == "r" && cache_file_owned_by_current_process?(opened)
+          apply_cache_mode_if_supported(handle, mode)
+          replacement = reopen_cache_lock_writable(path, purpose: purpose)
+          if replacement
+            retired = handle
+            handle = replacement
+            replacement = nil
+            access = "r+"
+            retired.close
+            retired = nil
+          end
+        end
+        succeeded = true
+        [handle, access, created]
+      rescue Errno::ELOOP, Errno::EISDIR, Errno::ENXIO => e
+        raise Error, "#{purpose} lock is not a regular file: #{path}", cause: e
+      ensure
+        retired.close if retired && !retired.closed?
+        replacement.close if replacement && !replacement.closed?
+        handle.close if handle && !succeeded && !handle.closed?
+        ::IO.new(descriptor).close if descriptor
+      end
+
+      def open_or_create_cache_lock_descriptor(path, flags, mode)
+        2.times do
+          return [::IO.sysopen(path.to_s, flags, mode), false]
+        rescue Errno::ENOENT
+          begin
+            return [::IO.sysopen(path.to_s, flags | File::CREAT | File::EXCL, mode), true]
+          rescue Errno::EEXIST
+            next
+          end
+        end
+
+        raise Errno::ENOENT, path.to_s
+      end
+
+      def open_readonly_cache_lock_descriptor(path, purpose:, write_error:)
+        ::IO.sysopen(path.to_s, readonly_cache_lock_flags)
+      rescue Errno::EACCES => e
+        raise Error,
+              "#{purpose} lock is not readable at #{path}; ask the cache owner to grant shared read/write access, " \
+              "or remove the stale lock only after all downloads have stopped",
+              cause: e
+      rescue Errno::ENOENT => e
+        raise Error, "Cannot create #{purpose.downcase} lock at #{path}: #{write_error.message}", cause: e
+      end
+
+      def reopen_cache_lock_writable(path, purpose:)
+        handle = nil
+        succeeded = false
+        descriptor = ::IO.sysopen(path.to_s, cache_lock_flags)
+        handle = File.new(descriptor, "r+", autoclose: true)
+        descriptor = nil
+        verify_cache_lock_identity!(path, handle, purpose: purpose)
+        succeeded = true
+        handle
+      rescue Errno::EACCES, Errno::EROFS
+        nil
+      ensure
+        handle&.close unless succeeded
         ::IO.new(descriptor).close if descriptor
       end
 
+      def cache_lock_flags
+        flags = File::RDWR
+        flags |= File::NOFOLLOW if defined?(File::NOFOLLOW)
+        flags |= File::CLOEXEC if defined?(File::CLOEXEC)
+        flags
+      end
+
+      def readonly_cache_lock_flags
+        flags = File::RDONLY
+        flags |= File::NOFOLLOW if defined?(File::NOFOLLOW)
+        flags |= File::CLOEXEC if defined?(File::CLOEXEC)
+        flags
+      end
+
+      def acquire_download_lock!(lock, path, destination)
+        return if lock.flock(File::LOCK_EX)
+
+        raise Error, "Cannot acquire Hub download lock for #{destination} at #{path}"
+      rescue SystemCallError => e
+        if e.is_a?(Errno::EBADF)
+          detail = "the filesystem requires a writable shared lock file"
+        elsif cache_locking_unsupported?(e)
+          detail = "the filesystem does not provide the required file locking"
+        else
+          raise
+        end
+        raise Error, "Cannot acquire Hub download lock for #{destination}: #{detail} at #{path}", cause: e
+      end
+
+      def cache_locking_unsupported?(error)
+        names = %i[ENOLCK EOPNOTSUPP ENOTSUP]
+        names.any? { |name| Errno.const_defined?(name) && error.errno == Errno.const_get(name)::Errno }
+      end
+
+      def cache_file_owned_by_current_process?(stat)
+        Process.respond_to?(:euid) && stat.uid == Process.euid
+      end
+
+      def verify_cache_lock_identity!(path, lock, purpose:)
+        opened = lock.stat
+        current = path.lstat
+        return opened if opened.file? && !current.symlink? && opened.dev == current.dev && opened.ino == current.ino
+
+        raise Error, "#{purpose} lock changed while held or is not a regular file: #{path}"
+      rescue SystemCallError => e
+        raise Error, "#{purpose} lock changed while held or is not a regular file: #{path}", cause: e
+      end
+
       # Build each repository subdirectory only after proving that its parent is
       # still inside this repository. This prevents a poisoned snapshots/refs
       # symlink from redirecting a Tempfile and rename outside the cache.
-      def prepare_cache_directory!(repository, directory)
+      def prepare_cache_directory!(repository, directory, replaceable_entries: false)
         FileUtils.mkdir_p(cache_dir)
         cache_root = cache_dir.realpath
         begin
-          Dir.mkdir(repository, 0o755)
+          create_cache_directory(repository, cache_dir)
         rescue Errno::EEXIST
-          nil
+          normalize_existing_cache_directory(repository, replaceable_entries: false)
         end
 
         repository_stat = repository.lstat
@@ -364,9 +625,9 @@ module Cohere
 
           current = current.join(part)
           begin
-            Dir.mkdir(current, 0o755)
+            create_cache_directory(current, current.dirname, replaceable_entries: replaceable_entries)
           rescue Errno::EEXIST
-            nil
+            normalize_existing_cache_directory(current, replaceable_entries: replaceable_entries)
           end
           resolved = current.realpath
           unless resolved.directory? && within_directory?(resolved, repository_root)
@@ -380,6 +641,133 @@ module Cohere
         raise Error, "Cannot prepare Hub cache directory #{directory}: #{e.message}"
       end
 
+      def create_cache_directory(path, parent, replaceable_entries: false)
+        # New cache directories inherit the verified parent's ordinary access
+        # bits and setgid policy even when this process has a private umask.
+        # Owner access keeps a newly-created private cache usable.
+        mode = cache_directory_mode(parent, replaceable_entries: replaceable_entries)
+        Dir.mkdir(path, mode)
+        flags = File::RDONLY
+        flags |= File::NOFOLLOW if defined?(File::NOFOLLOW)
+        flags |= File::CLOEXEC if defined?(File::CLOEXEC)
+        File.open(path, flags) do |handle|
+          opened = handle.stat
+          current = path.lstat
+          unless opened.directory? && !current.symlink? && opened.dev == current.dev && opened.ino == current.ino
+            raise Error, "Hub cache directory changed while it was being created: #{path}"
+          end
+
+          apply_cache_mode_if_supported(handle, mode)
+        end
+      end
+
+      def normalize_existing_cache_directory(path, replaceable_entries:)
+        return if replaceable_entries
+
+        flags = File::RDONLY
+        flags |= File::NOFOLLOW if defined?(File::NOFOLLOW)
+        flags |= File::CLOEXEC if defined?(File::CLOEXEC)
+        File.open(path, flags) do |handle|
+          opened = handle.stat
+          current = path.lstat
+          unless opened.directory? && !current.symlink? && opened.dev == current.dev && opened.ino == current.ino
+            raise Error, "Hub cache directory changed while its mode was being updated: #{path}"
+          end
+          next unless cache_file_owned_by_current_process?(opened)
+
+          current_mode = opened.mode & 0o3777
+          desired_mode = current_mode | (current_mode.anybits?(0o022) ? 0o1000 : 0)
+          apply_cache_mode_if_supported(handle, desired_mode) if current_mode != desired_mode
+        end
+      rescue Errno::EACCES, Errno::EROFS, Errno::ENOENT, Errno::ELOOP
+        nil
+      end
+
+      def normalize_cached_file_mode(path, desired_mode)
+        return if path.lstat.symlink?
+
+        flags = File::RDONLY
+        flags |= File::NOFOLLOW if defined?(File::NOFOLLOW)
+        flags |= File::CLOEXEC if defined?(File::CLOEXEC)
+        File.open(path, flags) do |handle|
+          opened = handle.stat
+          current = path.lstat
+          unless opened.file? && !current.symlink? && opened.dev == current.dev && opened.ino == current.ino
+            raise Error, "Hub cache file changed while its mode was being updated: #{path}"
+          end
+          next unless cache_file_owned_by_current_process?(opened)
+          next if (opened.mode & 0o777) == desired_mode
+
+          apply_cache_mode_if_supported(handle, desired_mode)
+        end
+      rescue Errno::EACCES, Errno::EROFS, Errno::ENOENT, Errno::ELOOP
+        nil
+      end
+
+      def normalize_cached_payload(repository, path)
+        repository_root = repository.realpath
+        relative = path.dirname.relative_path_from(repository)
+        return if relative.absolute? || relative.each_filename.any? { |part| part == ".." }
+
+        current = repository
+        normalize_existing_cache_directory(current, replaceable_entries: false)
+        components = relative.each_filename.reject { |part| part == "." }
+        until components.empty?
+          part = components.shift
+
+          current = current.join(part)
+          resolved = current.realpath
+          return unless resolved.directory? && within_directory?(resolved, repository_root)
+
+          normalize_existing_cache_directory(current, replaceable_entries: false)
+        end
+        normalize_cached_file_mode(path, cache_payload_mode(path.dirname))
+      rescue Error, SystemCallError, ArgumentError
+        # Reusing a verified immutable payload does not depend on being able to
+        # upgrade access modes in an older or read-only cache.
+        nil
+      end
+
+      def cache_directory_mode(parent, replaceable_entries: false)
+        parent_mode = parent.stat.mode
+        mode = 0o700 | (parent_mode & 0o2000)
+        mode |= parent_mode & 0o070 if parent_mode.anybits?(0o010)
+        mode |= parent_mode & 0o007 if parent_mode.anybits?(0o001)
+        # Snapshot directories keep other users from replacing published
+        # payloads. Ref directories omit this bit so collaborators can replace
+        # one another's advisory branch hints through atomic rename.
+        mode |= 0o1000 if !replaceable_entries && mode.anybits?(0o022)
+        mode
+      end
+
+      def cache_payload_mode(parent)
+        # Published payloads and refs inherit read access, never collaborator
+        # write access. Ref replacement is provided by the parent directory.
+        parent_mode = parent.stat.mode
+        mode = 0o600
+        mode |= 0o040 if parent_mode.allbits?(0o050)
+        mode |= 0o004 if parent_mode.allbits?(0o005)
+        mode
+      end
+
+      def cache_lock_mode(parent)
+        # Lock files must be writable by every collaborator who can create
+        # cache entries in the containing directory.
+        parent_mode = parent.stat.mode
+        mode = 0o600
+        mode |= 0o060 if parent_mode.allbits?(0o030)
+        mode |= 0o006 if parent_mode.allbits?(0o003)
+        mode
+      end
+
+      def apply_cache_mode_if_supported(target, mode)
+        target.chmod(mode)
+      rescue SystemCallError => e
+        raise unless CACHE_MODE_UNSUPPORTED_ERRNOS.include?(e.errno)
+
+        nil
+      end
+
       def within_directory?(path, directory)
         path_text = path.to_s
         directory_text = directory.to_s