woods 1.6.1 → 2.0.0.beta2

data/lib/woods/unblocked/client.rb

@@ -51,6 +51,28 @@ module Woods
       # the API docs marking it optional), so a working default matters.
       DEFAULT_ICON_URL = 'https://raw.githubusercontent.com/lost-in-the/woods/main/assets/woods-mark-black.svg'
 
+      # HTTP methods safe to retry after *any* transient network failure —
+      # repeating an idempotent request cannot double-apply an operation.
+      # PUT belongs here because the documents endpoint is an upsert keyed
+      # on `uri`. POST (create_collection) is deliberately absent: see
+      # {#execute_http}.
+      IDEMPOTENT_METHODS = %i[get put delete head].freeze
+
+      # Network failures that provably occur before the server could have
+      # processed the request (the connection was never established), so a
+      # retry is safe even for non-idempotent verbs.
+      PRE_REQUEST_ERRORS = [Net::OpenTimeout, Errno::ECONNREFUSED].freeze
+
+      # Response codes potentially retried. 429 is safe for every verb — it
+      # means the server throttled the request before processing it. 503 is
+      # NOT unconditionally safe: that status proves the *origin* refused to
+      # process the request, but it can also be synthesized by an
+      # intermediary sitting in front of an origin that already committed
+      # the write, so the response alone doesn't prove non-commitment.
+      # {#request}'s `idempotent:` flag gates the 503 retry accordingly —
+      # see {#execute_http} for the equivalent network-level split.
+      RETRYABLE_STATUS_CODES = %w[429 503].freeze
+
       # @param api_token [String] Unblocked API token (Personal or Team)
       # @param rate_limiter [RateLimiter] Rate limiter instance
       # @raise [ArgumentError] if api_token is nil or empty
@@ -91,23 +113,14 @@ module Woods
       #   Woods mark.
       # @return [Hash] { "id" => "collection-uuid", "name" => "...", ... }
       def create_collection(name:, description:, icon_url: nil)
+        # Collections have no upsert key, so there's no idempotency key to
+        # offer the API — a 503 that turns out to be an intermediary's
+        # response for an already-committed create must not be retried.
         request(:post, 'collections', {
                   name: name,
                   description: description,
                   iconUrl: icon_url || DEFAULT_ICON_URL
-                })
-      end
-
-      # List all collections.
-      #
-      # @return [Array<Hash>] Collection objects
-      def list_collections
-        result = request(:get, 'collections')
-        # The live API returns a bare JSON array; the envelope fallbacks are
-        # defensive (calling ['items'] on an Array raises TypeError).
-        return result if result.is_a?(Array)
-
-        result['items'] || result['data'] || [result].flatten.compact
+                }, idempotent: false)
       end
 
       # Delete a document by ID.
@@ -166,7 +179,18 @@ module Woods
 
       private
 
-      def request(method, path, body = nil)
+      # @param method [Symbol] HTTP method
+      # @param path [String] API path (appended to BASE_URL)
+      # @param body [Hash, nil] Request body
+      # @param idempotent [Boolean] Whether repeating this request cannot
+      #   double-apply the operation. 429 always retries regardless; a 503
+      #   only retries when `idempotent` is true, since a 503 can be an
+      #   intermediary's response for an origin that already committed a
+      #   non-idempotent write (see {RETRYABLE_STATUS_CODES}).
+      # @raise [Woods::Error] on non-success responses (after retries for 429,
+      #   and for 503 when idempotent), or immediately for a non-idempotent
+      #   request's 503
+      def request(method, path, body = nil, idempotent: true)
         retries = 0
 
         loop do
@@ -174,7 +198,9 @@ module Woods
 
           return parse_response(response) if response.is_a?(Net::HTTPSuccess)
 
-          if response.code == '429' && retries < MAX_RETRIES
+          raise_ambiguous_response_error(method, response) if response.code == '503' && !idempotent
+
+          if RETRYABLE_STATUS_CODES.include?(response.code) && retries < MAX_RETRIES
             retries += 1
             # Retry-After may be an HTTP-date, which .to_f would collapse to
             # 0.0 — honoring it as-is would hammer a throttling server.
@@ -187,6 +213,18 @@ module Woods
         end
       end
 
+      # Perform the raw HTTP request with verb-aware network error retry.
+      #
+      # Idempotent verbs ({IDEMPOTENT_METHODS}) retry every transient
+      # failure. POST retries only failures that provably happened before
+      # the server could have processed the request ({PRE_REQUEST_ERRORS});
+      # a mid-exchange failure (Net::ReadTimeout, ECONNRESET) raises
+      # instead, because the request may have been fully delivered and
+      # committed server-side before the connection died. That matters here
+      # because the one live POST is create_collection: collections have no
+      # upsert key, so retrying a phantom-committed create mints a duplicate
+      # collection that no later sync reconciles (documents upsert by `uri`
+      # and are safe; collections are not).
       def execute_http(method, path, body)
         attempts = 0
         begin
@@ -199,14 +237,77 @@ module Woods
           req = build_request(method, uri, body)
           http.request(req)
         rescue Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNRESET, Errno::ECONNREFUSED => e
+          raise_ambiguous_network_error(method, e) unless safe_to_retry?(method, e)
+
           attempts += 1
-          raise Woods::Error, "Network error after #{attempts} retries: #{e.message}" if attempts > MAX_RETRIES
+          if attempts >= MAX_RETRIES
+            raise Woods::Error, "Network error after #{attempts} attempts: #{redact_token(e.message)}"
+          end
 
           sleep(2**attempts)
           retry
         end
       end
 
+      # Whether a failed request may be retried without risking a
+      # double-apply: either the verb is idempotent, or the failure class
+      # proves the request never reached the server.
+      def safe_to_retry?(method, error)
+        IDEMPOTENT_METHODS.include?(method) || PRE_REQUEST_ERRORS.any? { |klass| error.is_a?(klass) }
+      end
+
+      # Raise for a non-idempotent request that failed mid-exchange. The
+      # request may have been committed server-side before the failure, so
+      # the operator must verify (e.g. list collections) before re-running
+      # rather than have the client silently duplicate the write.
+      def raise_ambiguous_network_error(method, error)
+        raise Woods::Error,
+              "#{method.to_s.upcase} request interrupted mid-exchange (#{error.class}); " \
+              'the operation may or may not have been applied server-side. ' \
+              'Not retrying automatically to avoid duplicates; verify before re-running: ' \
+              "#{redact_token(error.message)}"
+      end
+
+      # Raise for a non-idempotent request that received a 503. The response
+      # doesn't prove the origin never processed the request — an
+      # intermediary can synthesize a 503 for a request the origin already
+      # committed — so this mirrors {#raise_ambiguous_network_error}: same
+      # error class, same "verify before re-running" guidance, because the
+      # risk (a silently duplicated create) is identical.
+      #
+      # @param method [Symbol] HTTP method
+      # @param response [Net::HTTPResponse] the 503 response
+      # @raise [Woods::Error] always
+      def raise_ambiguous_response_error(method, response)
+        parsed = begin
+          JSON.parse(response.body)
+        rescue JSON::ParserError, TypeError
+          {}
+        end
+        detail = parsed['message'] || parsed['detail'] || parsed['title'] || 'Service Unavailable'
+        raise Woods::Error,
+              "#{method.to_s.upcase} request received 503 (#{redact_token(detail)}); " \
+              'the operation may or may not have been applied server-side. ' \
+              'Not retrying automatically to avoid duplicates; verify before re-running.'
+      end
+
+      # Strip the bearer token out of anything derived from an underlying
+      # network error before it reaches a log or a backtrace.
+      #
+      # The stdlib can echo a reflected URL or a request dump into an
+      # exception message, and this client sends the token in an Authorization
+      # header on every request. The Notion client has done this since its
+      # audit; this one had not, so the same class of leak was still open here.
+      #
+      # @param message [String, nil]
+      # @return [String, nil]
+      def redact_token(message)
+        return message if message.nil? || message.empty?
+        return message if @api_token.nil? || @api_token.empty?
+
+        message.to_s.gsub(@api_token, '[REDACTED]')
+      end
+
       def build_request(method, uri, body)
         req = case method
               when :put then Net::HTTP::Put.new(uri)
@@ -240,7 +341,8 @@ module Woods
         # The Unblocked API returns RFC7807-style bodies ({ status, title, detail });
         # older/other paths use message/error. Check all so failures stay legible.
         message = parsed['message'] || parsed['error'] || parsed['detail'] || parsed['title'] || 'Unknown error'
-        raise ApiError.new("Unblocked API error #{response.code}: #{message}", status: response.code.to_i)
+        raise ApiError.new("Unblocked API error #{response.code}: #{redact_token(message)}",
+                           status: response.code.to_i)
       end
     end
   end

data/lib/woods/unblocked/document_builder.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'erb' # ERB::Util.url_encode
 require 'woods/export/unit_facts'
 
 module Woods
@@ -18,10 +19,21 @@ module Woods
     #
     class DocumentBuilder
       # @param repo_url [String] GitHub repo base URL for citation URIs
-      def initialize(repo_url:)
+      # @param repo_url [String] Repository web URL, e.g. https://github.com/acme/app
+      # @param ref [String, nil] Branch/tag/SHA the index was extracted from.
+      #   Defaults to +DEFAULT_REF+ when nil, empty, or "unknown" — which is
+      #   what {Woods::GitProvenance} reports when it cannot resolve a ref.
+      def initialize(repo_url:, ref: nil)
         @repo_url = repo_url.chomp('/')
+        @ref = normalize_ref(ref)
       end
 
+      # Ref used when the index does not say which one it came from.
+      DEFAULT_REF = 'main'
+
+      # Refs that mean "no answer" rather than an actual ref name.
+      UNRESOLVED_REFS = ['', 'unknown'].freeze
+
       # Build a document hash from a unit's extracted data.
       #
       # @param unit_data [Hash] Parsed unit JSON (from IndexReader)
@@ -48,11 +60,31 @@ module Woods
         file_path = unit_data['file_path']
         return @repo_url unless file_path
 
-        "#{@repo_url}/blob/main/#{file_path}"
+        "#{@repo_url}/blob/#{@ref}/#{encode_path(file_path)}"
       end
 
       private
 
+      # `main` was hardcoded, so every citation on a repo whose default branch
+      # is `master` (or a release branch, or a tag) pointed at a ref that may
+      # not contain the file at all.
+      def normalize_ref(ref)
+        candidate = ref.to_s.strip
+        return DEFAULT_REF if UNRESOLVED_REFS.include?(candidate.downcase)
+
+        candidate
+      end
+
+      # Percent-encode each path segment, leaving the separators alone.
+      #
+      # Paths were interpolated raw, so a space or `#` in a filename produced a
+      # URL that silently truncated or 404'd — `#` in particular turns the rest
+      # of the path into a fragment. Encoding per segment rather than whole
+      # keeps `/` meaningful.
+      def encode_path(file_path)
+        file_path.to_s.split('/').map { |segment| ERB::Util.url_encode(segment) }.join('/')
+      end
+
       def build_body(unit_data)
         type = unit_data['type']
         body = case type

data/lib/woods/unblocked/exporter.rb

@@ -75,7 +75,10 @@ module Woods
 
         @client = client || Client.new(api_token: api_token, rate_limiter: limiter)
         @reader = reader || build_reader(index_dir)
-        @builder = DocumentBuilder.new(repo_url: repo_url)
+        # Cite the ref the index was actually extracted from. `main` was
+        # hardcoded, so citations on a `master`-default repo pointed at a
+        # branch that need not exist.
+        @builder = DocumentBuilder.new(repo_url: repo_url, ref: extracted_ref)
         @manifest = manifest || build_manifest(index_dir)
         @force_full = force_full
         @force_purge = force_purge
@@ -93,35 +96,37 @@ module Woods
       #
       # @return [Hash] { synced:, skipped:, deleted:, errors: }
       def sync_all
-        @current_uris = Set.new
-        @budget_exhausted = false
-        build_uri_index
-        reconcile_from_remote if @manifest.empty?
-
-        synced = 0
-        skipped = 0
-        errors = []
-
-        FULL_SYNC_TYPES.each do |type|
-          break if @budget_exhausted
+        with_pinned_index do
+          @current_uris = Set.new
+          @budget_exhausted = false
+          build_uri_index
+          reconcile_from_remote if @manifest.empty?
+
+          synced = 0
+          skipped = 0
+          errors = []
+
+          FULL_SYNC_TYPES.each do |type|
+            break if @budget_exhausted
+
+            result = sync_type(type)
+            synced += result[:synced]
+            skipped += result[:skipped]
+            errors.concat(result[:errors])
+          end
 
-          result = sync_type(type)
-          synced += result[:synced]
-          skipped += result[:skipped]
-          errors.concat(result[:errors])
-        end
+          PARTIAL_SYNC_TYPES.each do |type, max_count|
+            break if @budget_exhausted
 
-        PARTIAL_SYNC_TYPES.each do |type, max_count|
-          break if @budget_exhausted
+            result = sync_type_partial(type, max_count)
+            synced += result[:synced]
+            skipped += result[:skipped]
+            errors.concat(result[:errors])
+          end
 
-          result = sync_type_partial(type, max_count)
-          synced += result[:synced]
-          skipped += result[:skipped]
-          errors.concat(result[:errors])
+          deleted = @budget_exhausted ? 0 : purge_stale(errors)
+          { synced: synced, skipped: skipped, deleted: deleted, errors: cap_errors(errors) }
         end
-
-        deleted = @budget_exhausted ? 0 : purge_stale(errors)
-        { synced: synced, skipped: skipped, deleted: deleted, errors: cap_errors(errors) }
       ensure
         save_manifest
       end
@@ -173,6 +178,25 @@ module Woods
 
       private
 
+      # Run a multi-read export body against one index generation.
+      #
+      # Every public IndexReader accessor self-refreshes when the published
+      # generation moves, and the reader assigns pinning responsibility to
+      # direct callers. Unpinned, `build_uri_index`, the per-type listings and
+      # `purge_stale` can straddle two generations (EXP-5), so the purge set is
+      # computed against a mixture of them.
+      #
+      # Guarded by +respond_to?+: injected readers (specs, embedders) need not
+      # implement pinning.
+      #
+      # @yield the export body
+      # @return [Object] the block's value
+      def with_pinned_index(&block)
+        return yield unless @reader.respond_to?(:with_pinned_generation)
+
+        @reader.with_pinned_generation(&block)
+      end
+
       def sync_units(units)
         synced = 0
         skipped = 0
@@ -422,7 +446,7 @@ module Woods
       # message match remains as a fallback for injected clients that raise
       # plain Woods::Error.
       def note_budget_exhaustion(error)
-        return false unless error.is_a?(BudgetExhaustedError) || error.message.include?('daily budget exhausted')
+        return false unless error.is_a?(BudgetExhaustedError) || error.message.include?('budget exhausted for this run')
 
         @budget_exhausted = true
       end
@@ -432,6 +456,18 @@ module Woods
         Woods::MCP::IndexReader.new(index_dir)
       end
 
+      # The git ref recorded in the index manifest, for citation URLs.
+      #
+      # Nil on any failure — a missing or unreadable manifest must not stop a
+      # sync, and DocumentBuilder falls back to its default ref.
+      #
+      # @return [String, nil]
+      def extracted_ref
+        @reader.manifest['git_branch']
+      rescue StandardError
+        nil
+      end
+
       # Persist the manifest, downgrading failures to a warning: losing the
       # manifest only costs a full re-check next run, which must not turn an
       # otherwise-successful sync into a crash (this runs from an ensure, where

data/lib/woods/unblocked/rate_limiter.rb

@@ -10,11 +10,23 @@ module Woods
     # matching the message string.
     class BudgetExhaustedError < Woods::Error; end
 
-    # Daily budget-based rate limiter for the Unblocked API (1000 calls/day).
+    # Call-count budget for the Unblocked API, enforced **per run**.
     #
-    # Unlike Notion's per-second throttling, Unblocked limits by daily call count.
-    # Tracks usage against a configurable budget, warns when approaching the limit,
-    # and raises when exhausted.
+    # Unlike Notion's per-second throttling, Unblocked limits by daily call
+    # count (1000/day). This limiter is a guard rail against a single run
+    # burning that allowance, not a reimplementation of it: the counter lives
+    # in the process and starts at zero every run.
+    #
+    # That is deliberate rather than an oversight. The real budget is enforced
+    # server-side against the token, and the token is typically shared across
+    # developer machines and CI runners with no common disk — so a persisted
+    # local counter would be wrong in both directions (blocking a fresh run
+    # that had allowance left, and permitting a run after the allowance was
+    # spent elsewhere) while looking authoritative. A per-run cap gives the
+    # useful half of the guarantee honestly.
+    #
+    # Messages therefore say "per run", and the operator is pointed at the
+    # server-side limit for the real answer.
     #
     # @example
     #   limiter = RateLimiter.new(daily_budget: 1000)
@@ -50,8 +62,10 @@ module Woods
         @mutex.synchronize do
           if @calls_today >= @daily_budget
             raise BudgetExhaustedError,
-                  "Unblocked API daily budget exhausted (#{@daily_budget} calls). " \
-                  'Budget resets at midnight PST. Use UNBLOCKED_DAILY_BUDGET to adjust.'
+                  "Unblocked API call budget exhausted for this run (#{@daily_budget} calls). " \
+                  'This is a per-run cap, not a reading of your remaining daily allowance — ' \
+                  'the 1000/day limit is enforced server-side against your token and resets ' \
+                  'at midnight PST. Raise or lower the per-run cap with UNBLOCKED_DAILY_BUDGET.'
           end
 
           @calls_today += 1
@@ -61,7 +75,7 @@ module Woods
         yield
       end
 
-      # Number of API calls remaining in the daily budget.
+      # Number of API calls remaining in this run's budget.
       #
       # @return [Integer]
       def remaining
@@ -93,8 +107,8 @@ module Woods
 
         @warned = true
         @warn_io&.puts(
-          "WARNING: Unblocked API usage at #{@calls_today}/#{@daily_budget} " \
-          "(#{remaining} calls remaining)"
+          "WARNING: Unblocked API usage at #{@calls_today}/#{@daily_budget} for this run " \
+          "(#{remaining} calls remaining in the per-run cap)"
         )
       end
     end

data/lib/woods/unblocked/sync_manifest.rb

@@ -3,6 +3,8 @@
 require 'json'
 require 'fileutils'
 
+require_relative '../atomic_file'
+
 module Woods
   module Unblocked
     # Tracks what was last pushed to an Unblocked collection so a sync can
@@ -89,29 +91,33 @@ module Woods
       # Persist the manifest atomically (temp file + rename) so an interrupted
       # write never leaves a torn file in the CI cache.
       def save
-        FileUtils.mkdir_p(File.dirname(@path))
         payload = JSON.generate(
           'version' => VERSION,
           'collection_id' => @collection_id,
           'documents' => @documents
         )
-        tmp = "#{@path}.tmp"
-        File.write(tmp, payload)
-        File.rename(tmp, @path)
+        AtomicFile.write(@path, payload)
       end
 
       private
 
       # Load the persisted documents, discarding data from a different
-      # collection, a different schema version, or an unparseable file.
-      # Every discard warns to stderr — the consequence (a full re-push) is
-      # expensive enough that operators need to know why it happened.
+      # collection, a different schema version, or an unparseable/unreadable
+      # file. Every discard warns to stderr — the consequence (a full re-push)
+      # is expensive enough that operators need to know why it happened.
+      #
+      # AtomicFile.read, not File.read: a bare read tags the bytes with the
+      # process's default external encoding (US-ASCII under LANG=C), so a
+      # non-ASCII document URI raised EncodingError out of JSON.parse instead
+      # of degrading. Read failures (e.g. Errno::EACCES) take the same discard
+      # path — the manifest is a cache, and "everything is new" is always a
+      # correct answer.
       #
       # @return [Hash{String=>Hash}] uri => { 'hash' =>, 'document_id' => }
       def load
         return {} unless File.exist?(@path)
 
-        parsed = JSON.parse(File.read(@path))
+        parsed = JSON.parse(AtomicFile.read(@path))
         return discard('not a JSON object') unless parsed.is_a?(Hash)
         return discard("schema version #{parsed['version'].inspect}, expected #{VERSION}") unless
           parsed['version'] == VERSION
@@ -122,6 +128,8 @@ module Woods
         documents.is_a?(Hash) ? documents : {}
       rescue JSON::ParserError
         discard('unparseable JSON')
+      rescue EncodingError, SystemCallError => e
+        discard("unreadable file: #{e.class}: #{e.message}")
       end
 
       # @param reason [String] Why the persisted manifest is unusable

data/lib/woods/update_check.rb

@@ -62,12 +62,21 @@ module Woods
     # The +server.update+ sub-hash for +woods_status+. Keys are snake_case to
     # match the rest of the status payload's JSON shape.
     #
+    # +latest_version+ reports the newest version this process knows about —
+    # the published one when it is ahead of the install, otherwise the
+    # installed version itself. Reporting the raw published version here made
+    # the payload self-contradictory whenever the installed gem was newer (an
+    # unreleased build): +current_version: 2.0.0+ next to +latest_version:
+    # 1.6.0+ with +update_available: false+ reads as if the running version is
+    # invalid. +update_available+ semantics are unchanged: true only when the
+    # published version is strictly newer than the installed one.
+    #
     # @return [Hash] +{ current_version:, latest_version:, update_available: }+
     def status_hash(current: Woods::VERSION, **opts)
       r = check(current: current, **opts)
       {
         current_version: r[:current],
-        latest_version: r[:latest],
+        latest_version: newest_known_version(r[:current], r[:latest]),
         update_available: r[:update_available]
       }
     end
@@ -99,6 +108,20 @@ module Woods
       { current: current, latest: latest, update_available: latest ? newer?(latest, current) : false }
     end
 
+    # The newest version between the installed gem and the last published one
+    # this process knows about. Used by {status_hash} for public reporting;
+    # the raw published value stays internal for comparison and caching.
+    #
+    # @param current [String] installed version
+    # @param published [String, nil] last known published version (nil when
+    #   the probe failed or the check is disabled)
+    # @return [String]
+    def newest_known_version(current, published)
+      return current unless published && newer?(published, current)
+
+      published
+    end
+
     def newer?(latest, current)
       Gem::Version.new(latest) > Gem::Version.new(current)
     rescue ArgumentError

data/lib/woods/util/uuid5.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module Woods
+  module Util
+    # RFC 4122 / RFC 9562 name-based UUID version 5 (SHA-1) generation.
+    #
+    # Ruby's stdlib has no UUIDv5 primitive (`SecureRandom.uuid` is v4 —
+    # random, therefore useless for deriving a stable id from a name), so
+    # the digest is assembled here from {Digest::SHA1}.
+    #
+    # The output is a pure function of `(namespace, name)`: no clock, no
+    # randomness, no locale, no hash-ordering. Every input to the digest is
+    # a byte string derived deterministically, which is what makes the
+    # result identical across processes, machines, and Ruby versions —
+    # `Digest::SHA1` is a fixed standard, and the byte layout below is
+    # spelled out explicitly rather than relying on any Ruby-version
+    # behaviour.
+    #
+    # @example
+    #   Woods::Util::UUID5.generate(Woods::Util::UUID5::NAMESPACE_DNS, 'python.org')
+    #   # => "886313e1-3b8a-5372-9b90-0c9aee199e5d"
+    #
+    module UUID5
+      # The predefined DNS namespace from RFC 4122 Appendix C. Present so
+      # derived namespaces can be computed (and asserted) from a published
+      # constant rather than a magic literal.
+      NAMESPACE_DNS = '6ba7b810-9dad-11d1-80b4-00c04fd430c8'
+
+      # Canonical 8-4-4-4-12 hex form, case-insensitive.
+      UUID_PATTERN = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i
+
+      # Hex-digit group lengths of the canonical textual form.
+      GROUP_LENGTHS = [8, 4, 4, 4, 12].freeze
+      private_constant :GROUP_LENGTHS
+
+      # Generate the version 5 UUID for +name+ within +namespace+.
+      #
+      # @param namespace [String] Namespace UUID in canonical 8-4-4-4-12 form
+      # @param name [String] The name to hash within the namespace
+      # @return [String] Lowercase canonical UUIDv5
+      # @raise [ArgumentError] if +namespace+ is not a canonical UUID
+      def self.generate(namespace, name)
+        digest = Digest::SHA1.digest(pack_uuid(namespace) + name_bytes(name))
+        format_uuid(apply_version_and_variant(digest.bytes.first(16)))
+      end
+
+      # Is +value+ a canonical textual UUID?
+      #
+      # @param value [Object]
+      # @return [Boolean]
+      def self.uuid?(value)
+        value.is_a?(String) && UUID_PATTERN.match?(value)
+      end
+
+      # Convert a canonical UUID string into its 16 raw big-endian bytes.
+      #
+      # @param uuid [String]
+      # @return [String] binary, 16 bytes
+      # @raise [ArgumentError] if +uuid+ is not canonical
+      def self.pack_uuid(uuid)
+        raise ArgumentError, "Namespace is not a canonical UUID: #{uuid.inspect}" unless uuid?(uuid)
+
+        [uuid.delete('-')].pack('H32')
+      end
+
+      # The name's UTF-8 bytes.
+      #
+      # UUIDv5 hashes *bytes*, so the encoding a Ruby String happens to
+      # carry is load-bearing: the same characters tagged US-ASCII and
+      # UTF-8 must hash identically or a re-embed under a different
+      # `LANG` would produce a different point id and duplicate rather
+      # than replace. ASCII-only strings already share their byte
+      # sequence with UTF-8; anything else is transcoded explicitly.
+      #
+      # ASCII-8BIT is the exception: it is not a character encoding to
+      # transcode *from*, it is "this string is already bytes". `String#encode`
+      # treats it as latin-1-ish and raises `UndefinedConversionError` on any
+      # high byte, so a binary-tagged name is passed through instead — which is
+      # what "hash the bytes" meant all along (STO-13).
+      #
+      # @param name [String]
+      # @return [String] binary
+      def self.name_bytes(name)
+        str = name.to_s
+        return str.b if str.encoding == Encoding::ASCII_8BIT
+
+        str = str.encode(Encoding::UTF_8) unless str.encoding == Encoding::UTF_8 || str.ascii_only?
+        str.b
+      end
+
+      # Stamp the version (5) and RFC 4122 variant bits into the digest.
+      #
+      # Byte 6 holds the version in its high nibble; byte 8 holds the
+      # variant in its two high bits. Both are masked before being set so
+      # the surrounding hash bits survive.
+      #
+      # @param bytes [Array<Integer>] 16 digest bytes
+      # @return [Array<Integer>] the same array, mutated
+      def self.apply_version_and_variant(bytes)
+        bytes[6] = (bytes[6] & 0x0f) | 0x50 # version 5
+        bytes[8] = (bytes[8] & 0x3f) | 0x80 # variant RFC 4122
+        bytes
+      end
+
+      # Render 16 bytes as the canonical lowercase 8-4-4-4-12 string.
+      #
+      # @param bytes [Array<Integer>]
+      # @return [String]
+      def self.format_uuid(bytes)
+        hex = bytes.pack('C16').unpack1('H*')
+        offset = 0
+        GROUP_LENGTHS.map do |len|
+          group = hex[offset, len]
+          offset += len
+          group
+        end.join('-')
+      end
+
+      private_class_method :pack_uuid, :name_bytes, :apply_version_and_variant, :format_uuid
+    end
+  end
+end