phronomy 0.28.0 → 0.29.0

data/lib/phronomy/embeddings/authentication_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "transport_error"
+
+module Phronomy
+  module Embeddings
+    # Provider refusal; this classification alone does not authorize retries.
+    # @api public
+    class AuthenticationError < TransportError; end
+  end
+end

data/lib/phronomy/embeddings/backends/ruby_llm_embeddings.rb

@@ -40,8 +40,12 @@ module Phronomy
         opts[:provider] = @provider if @provider
         opts[:assume_model_exists] = true if @assume_model_exists
         ::RubyLLM.embed(text, **opts).vectors
+      rescue ::RubyLLM::UnauthorizedError, ::RubyLLM::ForbiddenError => error
+        raise AuthenticationError.new(error.message, code: "embeddings.authentication_failed"), cause: error
+      rescue ::RubyLLM::RateLimitError => error
+        raise RateLimitError.new(error.message, code: "embeddings.rate_limited"), cause: error
       rescue ::RubyLLM::Error => error
-        raise TransportError, error.message
+        raise TransportError.new(error.message), cause: error
       end
     end
   end

data/lib/phronomy/embeddings/rate_limit_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "transport_error"
+
+module Phronomy
+  module Embeddings
+    # Provider refusal; this classification alone does not authorize retries.
+    # @api public
+    class RateLimitError < TransportError; end
+  end
+end

data/lib/phronomy/execution/execution_cancellation_error.rb

@@ -6,9 +6,9 @@ module Phronomy
   class ExecutionCancellationError < CancellationError
     attr_reader :outcomes
 
-    def initialize(message = "Execution cancelled", outcomes:)
+    def initialize(message = "Execution cancelled", outcomes:, code: nil)
       @outcomes = outcomes
-      super(message)
+      super(message, code: code)
     end
   end
 end

data/lib/phronomy/execution/execution_timeout_error.rb

@@ -6,9 +6,9 @@ module Phronomy
   class ExecutionTimeoutError < TimeoutError
     attr_reader :outcomes
 
-    def initialize(message = "Execution timed out", outcomes:)
+    def initialize(message = "Execution timed out", outcomes:, code: nil)
       @outcomes = outcomes
-      super(message)
+      super(message, code: code)
     end
   end
 end

data/lib/phronomy/execution/task_result.rb

@@ -308,8 +308,13 @@ module Phronomy
     def deliver_completion_callback(callback, value, error)
       callback.call(value, error)
     rescue => callback_error
-      Phronomy::RuntimeSettings.current.logger&.error do
-        "[TaskResult] on_complete callback raised #{callback_error.class}: #{callback_error.message}"
+      begin
+        Phronomy::RuntimeSettings.current.logger&.error do
+          "[TaskResult] on_complete callback raised #{callback_error.class}: #{callback_error.message}"
+        end
+      rescue
+        # Reporting must not interrupt delivery to the remaining observers.
+        nil
       end
     end
 

data/lib/phronomy/filter/filter_block_error.rb

@@ -6,8 +6,8 @@ module Phronomy
   class FilterBlockError < Error
     attr_reader :filter
 
-    def initialize(message, filter: nil)
-      super(message)
+    def initialize(message, filter: nil, code: nil)
+      super(message, code: code)
       @filter = filter
     end
   end

data/lib/phronomy/generation/low_confidence_error.rb

@@ -6,9 +6,9 @@ module Phronomy
   class LowConfidenceError < Error
     attr_reader :result
 
-    def initialize(result)
+    def initialize(result, code: nil)
       @result = result
-      super("Answer confidence #{result.confidence} is below the required threshold")
+      super("Answer confidence #{result.confidence} is below the required threshold", code: code)
     end
   end
 end

data/lib/phronomy/integrations/ordered_event_delivery.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require_relative "../common/error"
+
+module Phronomy
+  module Integrations
+    # Optional transport helper. Payload meaning and destinations belong to the app.
+    # @api public
+    class OrderedEventDelivery
+      class ClosedError < Phronomy::Error; end
+      class OverflowError < Phronomy::Error; end
+
+      # Close and drain after the block, preserving its result or original failure.
+      # A flush timeout limits waiting, not an in-flight network request.
+      # @api public
+      def self.open(deliver:, capacity: 256, batch_size: 32, flush_timeout: 30, prepare_batch: nil)
+        raise ArgumentError, "block required" unless block_given?
+        reject_event_loop!
+        validate_timeout!(flush_timeout)
+        raise ArgumentError, "deliver must be callable" unless deliver.respond_to?(:call)
+        delivery = new(capacity: capacity, batch_size: batch_size, prepare_batch: prepare_batch, &deliver)
+        begin
+          yield delivery
+        ensure
+          primary = $!
+          begin
+            delivery.close_and_wait(timeout: flush_timeout)
+          rescue => secondary
+            if primary
+              report_secondary(secondary)
+            else
+              raise
+            end
+          end
+        end
+      end
+
+      def self.reject_event_loop!
+        if Phronomy::Runtime.in_event_loop_context?
+          raise Phronomy::EventLoopReentrancyError, "delivery flush cannot block EventLoop"
+        end
+      end
+
+      def self.validate_timeout!(timeout)
+        valid = timeout.nil? || (timeout.is_a?(Numeric) && timeout.finite? && timeout >= 0)
+        raise ArgumentError, "flush timeout must be a finite nonnegative number or nil" unless valid
+      end
+
+      def self.report_secondary(error)
+        Phronomy.configuration.logger&.error("[OrderedEventDelivery] secondary delivery failure: #{error.class}: #{error.message}")
+      rescue
+        # Diagnostic reporting must not replace the primary application error.
+        nil
+      end
+      private_class_method :reject_event_loop!, :validate_timeout!, :report_secondary
+
+      # Construction does not start a worker or create a pool.
+      # @api public
+      def initialize(capacity: 256, batch_size: 32, prepare_batch: nil, &deliver)
+        raise ArgumentError, "deliver block required" unless deliver
+        unless capacity.is_a?(Integer) && capacity.positive? && batch_size.is_a?(Integer) && batch_size.positive?
+          raise ArgumentError, "capacity and batch_size must be positive Integers"
+        end
+        raise ArgumentError, "prepare_batch must be callable" if prepare_batch && !prepare_batch.respond_to?(:call)
+        @capacity, @batch_size = capacity, batch_size
+        @prepare_batch, @deliver = prepare_batch, deliver
+        @mutex = Mutex.new
+        @condition = ConditionVariable.new
+        @queue = []
+        @accepting = true
+        @worker = nil
+        @failure = nil
+      end
+
+      # Snapshot plain data; admission order is the queue insertion order.
+      # Capacity counts queued payloads, excluding the active batch.
+      # @api public
+      def publish(payload)
+        value = immutable_copy(payload)
+        ticket = @mutex.synchronize do
+          raise @failure if @failure
+          raise ClosedError.new("event delivery closed", code: "delivery.closed") unless @accepting
+          raise OverflowError.new("event delivery queue full", code: "delivery.capacity_exceeded") if @queue.length >= @capacity
+          @queue << value
+          next nil if @worker
+          @worker = {started: false}
+        end
+        start_drain(ticket) if ticket
+        error = @mutex.synchronize { @failure }
+        raise error if error
+        self
+      rescue => error
+        # Listener dispatch can log an exception and continue. Retain the failure
+        # for close while continuing to drain already accepted work if possible.
+        @mutex.synchronize do
+          @failure ||= error
+          @accepting = false
+        end
+        raise
+      end
+
+      # External callers only. Concurrent close calls observe the same drain.
+      # Timeout does not abort a network operation or settle the worker's result.
+      # @api public
+      def close_and_wait(timeout: nil)
+        self.class.send(:reject_event_loop!)
+        self.class.send(:validate_timeout!, timeout)
+        deadline = timeout && monotonic_now + timeout
+        @mutex.synchronize do
+          @accepting = false
+          while @worker
+            remaining = deadline && deadline - monotonic_now
+            raise Phronomy::TimeoutError, "event delivery flush timed out" if remaining && remaining <= 0
+            @condition.wait(@mutex, remaining)
+          end
+          raise @failure if @failure
+        end
+        self
+      end
+
+      private
+
+      def start_drain(ticket)
+        Phronomy::Blocking.call_async do
+          started = @mutex.synchronize do
+            ticket[:started] = true if @worker.equal?(ticket)
+          end
+          if started
+            begin
+              drain(ticket)
+            rescue => error
+              fail_worker(ticket, error)
+            ensure
+              finish_worker(ticket)
+            end
+          end
+        end.on_complete do |_value, error|
+          fail_worker(ticket, error) if error
+        end
+      rescue => error
+        fail_worker(ticket, error)
+      end
+
+      def drain(ticket)
+        loop do
+          batch = @mutex.synchronize do
+            if @queue.empty?
+              # Publish must observe queue emptiness and ownership release together.
+              release_worker(ticket)
+              nil
+            else
+              @queue.shift(@batch_size)
+            end
+          end
+          return unless batch
+          prepared = @prepare_batch ? @prepare_batch.call(batch.freeze) : batch
+          raise ArgumentError, "prepare_batch must return an Array" unless prepared.is_a?(Array)
+          immutable_copy(prepared).each { |payload| @deliver.call(payload) }
+        end
+      end
+
+      def fail_worker(ticket, error)
+        @mutex.synchronize do
+          @failure ||= error
+          @accepting = false
+          @queue.clear
+          # Logical cancellation can precede physical worker exit. Keep waiting
+          # for a started delivery; never mistake settled TaskResult for exit.
+          release_worker(ticket) unless ticket[:started]
+        end
+      end
+
+      def finish_worker(ticket)
+        @mutex.synchronize { release_worker(ticket) }
+      end
+
+      def release_worker(ticket)
+        return unless @worker.equal?(ticket)
+        @worker = nil
+        @condition.broadcast
+      end
+
+      def immutable_copy(value, ancestors = {})
+        case value
+        when Hash, Array
+          raise ArgumentError, "event payload must contain acyclic plain data" if ancestors[value.object_id]
+          path = ancestors.merge(value.object_id => true)
+          if value.is_a?(Hash)
+            value.to_h { |key, child| [immutable_copy(key, path), immutable_copy(child, path)] }.freeze
+          else
+            value.map { |child| immutable_copy(child, path) }.freeze
+          end
+        when String then value.dup.freeze
+        when Integer, Symbol, TrueClass, FalseClass, NilClass then value
+        when Float
+          raise ArgumentError, "event payload numbers must be finite" unless value.finite?
+          value
+        else
+          raise ArgumentError, "event payload must contain plain data: #{value.class}"
+        end
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/phronomy/multi_agent/persistence/team_execution_repository.rb

@@ -12,7 +12,7 @@ module Phronomy
           Phronomy::Persistence::StorageBoundary.call do
             raise Phronomy::Storage::SerializationError, "create_active requires an active TeamExecution" unless execution.active?
             record = Codec.encode_team_execution(execution)
-            admission do
+            admission(execution.team_id) do
               @view.atomic do |bound|
                 entry = bound.records(Phronomy::MultiAgent::Persistence::StorageSchema::EXECUTIONS).insert(key: execution.team_execution_id.to_s,
                   revision: Integer(execution.execution_revision), attributes: attributes(execution), record: record)
@@ -42,7 +42,7 @@ module Phronomy
               raise Phronomy::Storage::SerializationError, "Execution identity mismatch"
             end
             record = Codec.encode_team_execution(execution)
-            admission do
+            admission(execution.team_id) do
               @view.atomic do |bound|
                 entry = bound.records(Phronomy::MultiAgent::Persistence::StorageSchema::EXECUTIONS).replace(key: team_execution_id.to_s,
                   expected_revision: expected, next_revision: revision, attributes: attributes(execution),
@@ -92,7 +92,7 @@ module Phronomy
               conditions: [condition])
           rescue Phronomy::Storage::ConditionFailedError => error
             raise unless error.condition.equal?(condition)
-            raise Phronomy::AgentBusyError, error.message
+            raise Phronomy::MultiAgent::TeamBusyError.new(error.message, team_id: team_id), cause: error
           end
         end
 
@@ -100,11 +100,11 @@ module Phronomy
 
         def attributes(execution) = {owner: execution.team_id.to_s, active: execution.active?}
 
-        def admission
+        def admission(team_id)
           yield
         rescue Phronomy::Storage::UniqueConstraintError => error
           raise unless error.resource == Phronomy::MultiAgent::Persistence::StorageSchema::EXECUTIONS.id && error.constraint == :one_active_owner
-          raise Phronomy::AgentBusyError, error.message
+          raise Phronomy::MultiAgent::TeamBusyError.new(error.message, team_id: team_id), cause: error
         end
 
         def decode(entry, team_execution_id, owner: nil, revision: nil, active: nil)

data/lib/phronomy/multi_agent/team_busy_error.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "../common/error"
+
+module Phronomy
+  module MultiAgent
+    # Describes the Team itself, not a child Agent.
+    # @api public
+    class TeamBusyError < Phronomy::Error
+      attr_reader :team_id
+
+      def initialize(message = nil, team_id:)
+        @team_id = team_id.to_s.dup.freeze
+        super(message || "Team #{@team_id}: busy", code: "team.busy")
+      end
+    end
+  end
+end

data/lib/phronomy/multi_agent/team_coordinator.rb

@@ -188,11 +188,22 @@ module Phronomy
           begin
             store.transaction { |tx| tx.teams.create(intended) }
           rescue => error
-            confirmed = store.teams.load(id)
+            begin
+              confirmed = store.teams.load(id)
+            rescue
+              # A failed readback cannot turn an unknown create outcome into
+              # a claim that the Team is absent or safe to create again.
+              raise error, cause: error.cause
+            end
             raise error unless confirmed.to_h == intended.to_h
           end
         end
-        root = store.teams.load(id)
+        begin
+          root = store.teams.load(id)
+        rescue Phronomy::Persistence::NotFoundError => error
+          raise if create || error.is_a?(TeamNotFoundError)
+          raise TeamNotFoundError.new(team_id: id), cause: error
+        end
         unless root.team_definition_id == definition.fetch(:id) && root.team_definition_version == definition.fetch(:version)
           raise Phronomy::ConfigurationError, "Team #{id} definition mismatch"
         end
@@ -238,7 +249,7 @@ module Phronomy
         begin
           persistence.transaction do |tx, scope|
             root = tx.teams.load(team_id)
-            raise Phronomy::AgentBusyError, "Team #{team_id} has an active run; use resume" unless tx.team_executions.list_active(team_id).empty?
+            raise TeamBusyError.new("Team #{team_id} has an active run; use resume", team_id: team_id) unless tx.team_executions.list_active(team_id).empty?
             intended = TeamExecution.new(team_execution_id: id, team_id: team_id,
               execution_revision: 0, status: "active", phase: "coordinator", input_ref: tx.contents.put_text(input),
               coordinator: {"agent_id" => SecureRandom.uuid, "execution_id" => SecureRandom.uuid, "state" => "reserved"},
@@ -341,7 +352,7 @@ module Phronomy
               output = Phronomy::Values::Serializable.convert(aggregate ? aggregate.call(values) : values, unsupported_message: "Team result is not canonically serializable")
               Phronomy::CanonicalJSON.dump(output)
             rescue => error
-              return terminal_value(finish_error(id, {"class" => error.class.name.to_s, "message" => error.message.to_s}))
+              return terminal_value(finish_error(id, Phronomy::Error.diagnostic(error)))
             end
             # Aggregate may be replayed only until the canonical outcome commits.
             completed = update(id) do |fresh, tx, scope|
@@ -465,7 +476,7 @@ module Phronomy
         raise Phronomy::CancellationError, "Team run #{execution.team_execution_id} cancelled" if execution.status == "cancelled"
         if execution.error_ref
           failure = persistence.contents.fetch_json(execution.error_ref)
-          raise Phronomy::Error, "#{failure.fetch("class")}: #{failure.fetch("message")}"
+          raise Phronomy::Error.from_diagnostic(failure)
         end
         persistence.contents.fetch_json(execution.result_ref)
       end
@@ -514,7 +525,7 @@ module Phronomy
             Phronomy::Execution.submit(on_full: :raise) do
               team.send(:apply_operation, run_id, key, operation, arguments)
             rescue OperationRejected => error
-              raise Phronomy::ConfigurationError, error.message
+              raise Phronomy::ConfigurationError.new(error.message, code: error.code)
             rescue Phronomy::CancellationError
               raise
             rescue => error
@@ -551,7 +562,9 @@ module Phronomy
             name = entry.name
             values = entry.arguments
             if name == "enqueue_task"
-              raise OperationRejected, "Cannot enqueue after finalize" if metadata["finalized"]
+              if metadata["finalized"]
+                raise OperationRejected.new("Cannot enqueue after finalize", code: "team.enqueue_after_finalize")
+              end
               task = {"id" => Digest::SHA256.hexdigest(entry_id)[0, 32], "description" => values.fetch("description"), "metadata" => values["metadata"]}
               tasks << task
               output = "Task ##{tasks.length} enqueued: #{task.fetch("description")}"

data/lib/phronomy/multi_agent/team_not_found_error.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "../persistence/errors"
+
+module Phronomy
+  module MultiAgent
+    # Describes the Team itself, not a child Agent.
+    # @api public
+    class TeamNotFoundError < Phronomy::Persistence::NotFoundError
+      attr_reader :team_id
+
+      def initialize(message = nil, team_id:)
+        @team_id = team_id.to_s.dup.freeze
+        super(message || "Team #{@team_id}: not_found", code: "team.not_found")
+      end
+    end
+  end
+end

data/lib/phronomy/storage/condition_failed_error.rb

@@ -7,9 +7,9 @@ module Phronomy
     class ConditionFailedError < ConflictError
       attr_reader :condition
       # @api public
-      def initialize(condition)
+      def initialize(condition, code: nil)
         @condition = condition
-        super("storage condition failed: #{condition.class.name}")
+        super("storage condition failed: #{condition.class.name}", code: code)
       end
     end
   end

data/lib/phronomy/storage/unique_constraint_error.rb

@@ -7,10 +7,10 @@ module Phronomy
     class UniqueConstraintError < ConflictError
       attr_reader :resource, :constraint
       # @api public
-      def initialize(resource:, constraint:)
+      def initialize(resource:, constraint:, code: nil)
         @resource = resource.id
         @constraint = constraint
-        super("unique constraint #{resource.id}.#{constraint} failed")
+        super("unique constraint #{resource.id}.#{constraint} failed", code: code)
       end
     end
   end

data/lib/phronomy/testing/persistence_contract/coordination_repositories.rb

@@ -84,7 +84,7 @@ RSpec.shared_examples "a Team execution repository" do
   it "atomically admits at most one active run per Team" do
     stores.multi_agent.team_executions.create_active(coordination_run)
     other = coordination_run.with(team_execution_id: SecureRandom.uuid, execution_revision: 0)
-    expect { stores.multi_agent.team_executions.create_active(other) }.to raise_error(Phronomy::AgentBusyError)
+    expect { stores.multi_agent.team_executions.create_active(other) }.to raise_error(Phronomy::MultiAgent::TeamBusyError)
     expect(stores.multi_agent.team_executions.list_active(coordination_team.team_id).map(&:team_execution_id)).to eq([coordination_run.team_execution_id])
   end
 

data/lib/phronomy/tool/base.rb

@@ -383,8 +383,9 @@ module Phronomy
         if schema_error
           case self.class.on_schema_error
           when :raise
-            raise Phronomy::ToolError,
-              "#{self.class.name} schema error: #{schema_error}"
+            raise Phronomy::ToolError.new(
+              "#{self.class.name} schema error: #{schema_error}", code: "tool.invalid_arguments"
+            )
           else
             return "Schema validation failed: #{schema_error}"
           end
@@ -399,17 +400,12 @@ module Phronomy
         raise
       rescue => error
         if self.class.on_error == :suppress
-          msg = "[Phronomy] Tool #{self.class.name} suppressed error: " \
-            "#{error.class}: #{error.message}"
-          if Phronomy::RuntimeSettings.current.logger
-            Phronomy::RuntimeSettings.current.logger.warn(msg)
-          else
-            warn msg
-          end
+          report_suppressed_error(error)
           "Tool error suppressed: #{error.message}"
         else
-          raise Phronomy::ToolError,
-            "#{self.class.name} execution failed: #{error.message}"
+          raise Phronomy::ToolError.new(
+            "#{self.class.name} execution failed: #{error.message}", code: "tool.execution_failed"
+          ), cause: error
         end
       end
 
@@ -462,7 +458,9 @@ module Phronomy
         if schema_error
           return Phronomy::AsyncOperation.capture(name: "#{operation_name}-schema") do
             if self.class.on_schema_error == :raise
-              raise Phronomy::ToolError, "#{self.class.name} schema error: #{schema_error}"
+              raise Phronomy::ToolError.new(
+                "#{self.class.name} schema error: #{schema_error}", code: "tool.invalid_arguments"
+              )
             end
             "Schema validation failed: #{schema_error}"
           end
@@ -472,8 +470,9 @@ module Phronomy
           transform: method(:truncate_result_if_needed)) do
           source = yield(validated_args || {})
           unless source.respond_to?(:on_complete)
-            raise Phronomy::ToolError,
-              "#{self.class.name} asynchronous execution must return a completion handle"
+            raise Phronomy::ToolError.new(
+              "#{self.class.name} asynchronous execution must return a completion handle", code: "tool.invalid_async_result"
+            )
           end
           source
         end
@@ -488,23 +487,26 @@ module Phronomy
         end
 
         if self.class.on_error == :suppress
-          message = "[Phronomy] Tool #{self.class.name} suppressed error: " \
-            "#{error.class}: #{error.message}"
-          if Phronomy::RuntimeSettings.current.logger
-            Phronomy::RuntimeSettings.current.logger.warn(message)
-          else
-            warn message
-          end
+          report_suppressed_error(error)
           "Tool error suppressed: #{error.message}"
         else
           wrapped = Phronomy::ToolError.new(
-            "#{self.class.name} execution failed: #{error.message}"
+            "#{self.class.name} execution failed: #{error.message}", code: "tool.execution_failed"
           )
           wrapped.set_backtrace(error.backtrace)
-          raise wrapped
+          raise wrapped, cause: error
         end
       end
 
+      def report_suppressed_error(error)
+        message = "[Phronomy] Tool #{self.class.name} suppressed error: #{error.class}: #{error.message}"
+        logger = Phronomy::RuntimeSettings.current.logger
+        logger ? logger.warn(message) : warn(message)
+      rescue
+        # A diagnostic failure must not change the selected suppression policy.
+        nil
+      end
+
       def execute_accepts_cancellation_token?
         method(:execute).parameters.any? do |type, name|
           name == :cancellation_token && %i[key keyreq].include?(type)

data/lib/phronomy/tracing/base.rb

@@ -34,15 +34,44 @@ module Phronomy
       # @return [Object] the block's return value
       # @api public
       def trace(name, input: nil, **meta)
-        span = start_span(name, input: input, **meta)
-        result, usage = yield span
-        finish_span(span, output: result, usage: usage)
+        Base.trace_with(self, name, attributes: {input: input, **meta}) { |span| yield span }
+      end
+
+      # Use the public start/finish SPI, including duck-typed tracers.
+      # Start failures do not finish; finish is attempted once after execution.
+      # A secondary finish/reporting failure cannot replace the block's error.
+      # Set record_output: false for metadata-only operations.
+      # @api public
+      def self.trace_with(tracer, name, record_output: true, attributes: {})
+        span = tracer.start_span(name, **attributes)
+        begin
+          result, usage = yield span
+        rescue => primary
+          begin
+            tracer.finish_span(span, error: primary)
+          rescue => secondary
+            report_secondary(secondary)
+          end
+          raise
+        end
+        if record_output
+          tracer.finish_span(span, output: result, usage: usage)
+        else
+          tracer.finish_span(span)
+        end
         result
-      rescue => e
-        finish_span(span, error: e)
-        raise
       end
 
+      def self.report_secondary(error)
+        Phronomy::RuntimeSettings.current.logger&.warn(
+          "[Phronomy::Tracing] secondary finish failure: #{error.class}: #{error.message}"
+        )
+      rescue
+        # Diagnostics are best effort; preserve the primary business failure.
+        nil
+      end
+      private_class_method :report_secondary
+
       # Start a new span. Must return an object that will be passed to #finish_span.
       #
       # @param name [String]