docs: add YARD comments to public API surfaces

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: nficano

lib/arcp/auth/auth_scheme.rb

@@ -2,6 +2,7 @@
 
 module Arcp
   module Auth
+    # Authenticated principal returned by an `AuthScheme`.
     Principal = Data.define(:id, :name, :scopes)
 
     # AuthScheme is an interface: implementations expose

lib/arcp/auth/bearer.rb

@@ -3,15 +3,18 @@
 module Arcp
   module Auth
     # Static-token bearer verifier. Maps token strings to Principals.
+    #
     # For production, plug a custom verifier implementing
     # `#verify(token) -> Principal | nil`.
     class Bearer
       include AuthScheme
 
+      # Build a bearer verifier from a token-to-principal map.
       def initialize(tokens: {})
         @tokens = tokens.dup.freeze
       end
 
+      # Verify a bearer token and return the associated principal.
       def verify(token)
         return nil if token.nil?
 
@@ -30,6 +33,7 @@ def verify(token)
         end
       end
 
+      # Convenience constructor for a single accepted token.
       def self.from_token(token, principal_id: 'anonymous', scopes: [])
         new(tokens: { token => Principal.new(id: principal_id, name: principal_id, scopes: scopes.freeze) })
       end

lib/arcp/clock.rb

@@ -3,29 +3,40 @@
 require 'time'
 
 module Arcp
+  # Clock abstraction used by the runtime and tests.
   module Clock
     module_function
 
+    # Current monotonic time in seconds.
     def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    # Current wall-clock time in UTC.
     def now = Time.now.utc
   end
 
+  # Real clock wrapper for components that need an object.
   class SystemClock
+    # Current wall-clock time in UTC.
     def now = Time.now.utc
+    # Current monotonic time in seconds.
     def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
   end
 
+  # Deterministic clock used in tests.
   class FakeClock
     attr_accessor :now_value, :monotonic_value
 
+    # Start at a specific UTC instant and advance manually in tests.
     def initialize(now: Time.utc(2026, 1, 1))
       @now_value = now.utc
       @monotonic_value = 0.0
     end
 
+    # Current wall-clock time in UTC.
     def now = @now_value
+    # Current monotonic time in seconds.
     def monotonic = @monotonic_value
 
+    # Advance both wall-clock and monotonic time by `seconds`.
     def advance(seconds)
       @now_value += seconds
       @monotonic_value += seconds

lib/arcp/envelope.rb

@@ -76,6 +76,7 @@ def self.from_json(bytes)
       from_h(Arcp::Serializer.load(bytes))
     end
 
+    # @api private
     def self.deep_freeze(value)
       case value
       when Hash
@@ -97,6 +98,7 @@ def to_h
 
     def to_json(*_args) = Arcp::Serializer.dump(to_h)
 
+    # @api private
     def stringify(value)
       case value
       when Hash  then value.transform_keys(&:to_s).transform_values { |v| stringify(v) }
@@ -108,6 +110,7 @@ def stringify(value)
     def known? = Arcp::MessageTypes.known?(type)
   end
 
+  # @api private
   UnknownEnvelope = Data.define(:envelope) do
     def type = envelope.type
     def payload = envelope.payload

lib/arcp/errors.rb

@@ -21,6 +21,7 @@ def to_payload(trace_id: nil)
       payload
     end
 
+    # @api private
     def self.default_message = name.split('::').last.gsub(/([a-z])([A-Z])/, '\1 \2').downcase
   end
 

lib/arcp/ids.rb

@@ -3,16 +3,25 @@
 require 'securerandom'
 
 module Arcp
+  # Identifier helpers for protocol objects.
   module Ids
     module_function
 
+    # @api private
     def envelope_id = SecureRandom.uuid_v7
+    # @api private
     def session_id  = "ses_#{SecureRandom.uuid_v7}"
+    # @api private
     def job_id      = "job_#{SecureRandom.uuid_v7}"
+    # @api private
     def result_id   = "res_#{SecureRandom.uuid_v7}"
+    # @api private
     def call_id     = "call_#{SecureRandom.uuid_v7}"
+    # @api private
     def resume_token = SecureRandom.urlsafe_base64(24)
+    # @api private
     def trace_id    = SecureRandom.hex(16)
+    # @api private
     def span_id     = SecureRandom.hex(8)
   end
 end