smith-agents 0.4.4 → 0.5.0

data/lib/smith/agent/registry.rb

@@ -3,11 +3,15 @@
 require "dry-container"
 require "monitor"
 require_relative "registry_binding"
+require_relative "registry/execution_binding_capture"
+require_relative "registry/mutation_boundary"
 
 module Smith
   class Agent
     module Registry
       extend Dry::Container::Mixin
+      extend ExecutionBindingCapture
+      extend MutationBoundary
 
       def self.normalize_key(name)
         name.to_s
@@ -126,6 +130,10 @@ module Smith
           existing_name == klass_name
       end
       private_class_method :stale_reload_binding?
+
+      class << self
+        private :_container, :config
+      end
     end
   end
 end

data/lib/smith/agent.rb

@@ -56,10 +56,19 @@ module Smith
         @fallback_models_list = entries.uniq
       end
 
-      def register_as(name = nil)
+      def register_as(name = nil, publish: true)
         return @registered_name if name.nil?
 
-        @registered_name = name
+        raise ArgumentError, "publish must be true or false" unless [true, false].include?(publish)
+
+        @registered_name = canonical_registration_name(name)
+        publish ? publish_registration! : self
+      end
+
+      def publish_registration!
+        name = @registered_name
+        raise Smith::AgentRegistryError, "agent registration identity is not configured" unless name
+
         Registry.ensure_registered(name.to_sym, self)
       end
 
@@ -109,6 +118,19 @@ module Smith
 
       attr_reader :model_block
 
+      private
+
+      def canonical_registration_name(name)
+        symbol = name.to_sym
+        raise TypeError, "agent registration name must convert to a Symbol" unless symbol.is_a?(Symbol)
+
+        name.is_a?(String) ? name.dup.freeze : symbol
+      rescue NoMethodError
+        raise TypeError, "agent registration name must respond to #to_sym"
+      end
+
+      public
+
       # Whether this agent class has any model configured (static or block).
       # Smith::Workflow::Execution uses this as a precondition for invoking
       # the agent; agents declared without a model are skipped.

data/lib/smith/budget/amount_contract.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  module Budget
+    class AmountContract
+      extend Dry::Initializer
+
+      option :limits, default: proc {}
+
+      def own_hash!(amounts, label)
+        case amounts
+        when Hash then own_amount_hash(amounts, label)
+        else raise ArgumentError, "#{label} values must be a Hash"
+        end
+      end
+
+      def known_hash!(amounts)
+        amounts.each_key { known_dimension!(_1) }
+      end
+
+      def known_dimension!(key)
+        return if limits&.key?(key)
+
+        raise ArgumentError, "unknown budget dimension #{key.inspect}"
+      end
+
+      def matching_dimensions!(reserved, actual)
+        return if reserved.length == actual.length && reserved.each_key.all? { actual.key?(_1) }
+
+        raise ArgumentError, "reserved and actual budget dimensions must match"
+      end
+
+      def dimension!(key)
+        case key
+        when Symbol then key
+        when String then String.new(key).freeze
+        else raise ArgumentError, "budget dimension keys must be symbols or strings"
+        end
+      end
+
+      private
+
+      def own_amount_hash(amounts, label)
+        {}.tap do |owned|
+          Hash.instance_method(:each_pair).bind_call(amounts) do |key, amount|
+            owned[dimension!(key)] = own_amount!(amount, label)
+          end
+        end
+      end
+
+      def own_amount!(amount, label)
+        validate_amount!(amount, label)
+      end
+
+      def validate_amount!(amount, label)
+        case amount
+        when Integer then return amount if amount >= 0
+        when Float then return amount if amount.finite? && amount >= 0
+        end
+
+        raise ArgumentError, "#{label} values must be finite and non-negative Integer or Float values"
+      end
+    end
+  end
+end

data/lib/smith/budget/amount_representation.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "dry-initializer"
+
+module Smith
+  module Budget
+    class AmountRepresentation
+      extend Dry::Initializer
+
+      option :limits
+
+      def internalize(amounts)
+        amounts.to_h { |key, amount| [key, internalize_amount(amount)] }
+      end
+
+      def externalize(amounts)
+        amounts.to_h { |key, amount| [key, externalize_amount(key, amount)] }
+      end
+
+      def externalize_amount(key, amount)
+        return finite_float!(amount) if limits.fetch(key).is_a?(Float)
+        return amount if amount.is_a?(Integer)
+        return amount.to_i if amount.frac.zero?
+
+        finite_float!(amount)
+      end
+
+      private
+
+      def internalize_amount(amount)
+        BigDecimal(amount.to_s)
+      end
+
+      def finite_float!(amount)
+        external = amount.to_f
+        return external if external.finite?
+
+        raise ArgumentError, "budget state values must remain JSON-safe finite numerics"
+      end
+    end
+  end
+end

data/lib/smith/budget/decimal_context.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module Smith
+  module Budget
+    class DecimalContext
+      def self.call
+        BigDecimal.save_limit do
+          BigDecimal.limit(0)
+          yield
+        end
+      end
+
+      private_class_method :new
+    end
+  end
+end

data/lib/smith/budget/ledger.rb

@@ -1,41 +1,133 @@
 # frozen_string_literal: true
 
+require_relative "amount_contract"
+require_relative "amount_representation"
+require_relative "ledger_publication"
+require_relative "ledger_state"
+require_relative "ledger_state_transition"
+require_relative "public_state_validator"
+require_relative "reservation"
+require_relative "reservation_contract"
+
 module Smith
   module Budget
     class Ledger
-      attr_reader :limits, :consumed
+      attr_reader :limits
 
       def initialize(limits: {}, consumed: {})
         @mutex = Mutex.new
-        @limits = limits
-        @consumed = Hash.new(0).merge(consumed)
-        @reserved = Hash.new(0)
+        @identity = Object.new.freeze
+        @reservation_contract = ReservationContract.new(ledger_identity: @identity)
+        initialize_contracts(limits)
+        initialize_state(consumed)
       end
 
-      def reserve!(key, amount)
-        @mutex.synchronize do
-          committed = @consumed[key] + @reserved[key]
-          raise BudgetExceeded if committed + amount > @limits[key]
+      def consumed
+        @mutex.synchronize { @representation.externalize(@publication.state.consumed).freeze }
+      end
 
-          @reserved[key] += amount
-        end
+      def reserve!(key, amount) = reserve_many!(key => amount)
+
+      def reserve_many!(reservations)
+        amounts = validated_amounts(reservations, "budget reservation")
+        @mutex.synchronize { create_reservation(amounts) }
       end
 
-      def reconcile!(key, reserved_amount, actual_amount)
-        @mutex.synchronize do
-          @reserved[key] = [0, @reserved[key] - reserved_amount].max
-          @consumed[key] += actual_amount
+      def reconcile!(reservation, actual_amount)
+        amounts = @reservation_contract.amounts!(reservation)
+        unless amounts.one?
+          raise ArgumentError, "single-dimension reconciliation requires a single-dimension reservation"
         end
+
+        reconcile_many!(reservation, actual: { amounts.keys.first => actual_amount }).values.first
       end
 
-      def release!(key, amount)
+      def reconcile_many!(reservation, actual:)
+        token = @reservation_contract.token!(reservation)
+        actuals = validated_amounts(actual, "actual budget")
+        @mutex.synchronize { settle_reservation(token, actuals) }
+      end
+
+      def release!(reservation)
+        released = release_many!(reservation)
+        released.values.first if released.one?
+      end
+
+      def release_many!(reservation)
+        token = @reservation_contract.token!(reservation)
+        @mutex.synchronize { release_reservation(token) }
+      end
+
+      def remaining(key)
+        dimension = @amount_contract.dimension!(key)
+        @amount_contract.known_dimension!(dimension)
         @mutex.synchronize do
-          @reserved[key] = [0, @reserved[key] - amount].max
+          amount = @state_transition.remaining(@publication.state, dimension)
+          @representation.externalize_amount(dimension, amount)
         end
       end
 
-      def remaining(key)
-        @mutex.synchronize { [@limits[key] - @consumed[key] - @reserved[key], 0].max }
+      private
+
+      def initialize_contracts(limits)
+        @limits = AmountContract.new.own_hash!(limits, "budget limit").freeze
+        @amount_contract = AmountContract.new(limits: @limits)
+        @representation = AmountRepresentation.new(limits: @limits)
+        internal_limits = @representation.internalize(@limits)
+        @state_transition = LedgerStateTransition.new(limits: internal_limits)
+        @public_state_validator = PublicStateValidator.new(
+          limits: @limits,
+          representation: @representation,
+          state_transition: @state_transition
+        )
+      end
+
+      def initialize_state(consumed)
+        initial_consumed = @amount_contract.own_hash!(consumed, "consumed budget")
+        @amount_contract.known_hash!(initial_consumed)
+        internal_consumed = @representation.internalize(initial_consumed)
+        state = LedgerState.new(consumed: internal_consumed, reserved: {})
+        @publication = LedgerPublication.new(state: @public_state_validator.call(state))
+      end
+
+      def validated_amounts(amounts, label)
+        external = @amount_contract.own_hash!(amounts, label)
+        @amount_contract.known_hash!(external)
+        @representation.internalize(external)
+      end
+
+      def create_reservation(amounts)
+        token = Object.new.freeze
+        receipt = Reservation.new(
+          ledger_identity: @identity,
+          token:,
+          amounts: @representation.externalize(amounts)
+        )
+        next_state = @state_transition.reserve(@publication.state, amounts)
+        @publication.add(@public_state_validator.call(next_state), token:, amounts:)
+        receipt
+      end
+
+      def settle_reservation(token, actuals)
+        reserved_amounts = active_reservation!(token)
+        @amount_contract.matching_dimensions!(reserved_amounts, actuals)
+        next_state = @state_transition.reconcile(@publication.state, reserved_amounts, actuals)
+        consumed = @representation.externalize(next_state.consumed.slice(*actuals.keys))
+        @publication.remove(@public_state_validator.call(next_state), token:, amounts: reserved_amounts)
+        consumed
+      end
+
+      def release_reservation(token)
+        reserved_amounts = active_reservation!(token)
+        next_state = @state_transition.release(@publication.state, reserved_amounts)
+        remaining = @representation.externalize(next_state.reserved.slice(*reserved_amounts.keys))
+        @publication.remove(@public_state_validator.call(next_state), token:, amounts: reserved_amounts)
+        remaining
+      end
+
+      def active_reservation!(token)
+        @publication.reservation(token) ||
+          raise(ArgumentError, "budget reservation is unknown or already settled")
       end
     end
   end

data/lib/smith/budget/ledger_publication.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  module Budget
+    class LedgerPublication
+      extend Dry::Initializer
+
+      option :state
+      option :reservations, default: proc { {} }
+
+      private :reservations
+
+      def reservation(token)
+        reservations[token]
+      end
+
+      def add(next_state, token:, amounts:)
+        publish(
+          next_state,
+          commit: -> { reservations[token] = amounts },
+          rollback: -> { reservations.delete(token) }
+        )
+      end
+
+      def remove(next_state, token:, amounts:)
+        publish(
+          next_state,
+          commit: -> { reservations.delete(token) },
+          rollback: -> { reservations[token] = amounts }
+        )
+      end
+
+      private
+
+      def publish(next_state, commit:, rollback:)
+        previous_state = state
+        published = false
+        begin
+          Thread.handle_interrupt(Object => :never) do
+            @state = next_state
+            published = true
+            commit.call
+          end
+        rescue Exception # rubocop:disable Lint/RescueException
+          rollback(previous_state, rollback) if published
+          raise
+        end
+      end
+
+      def rollback(previous_state, operation)
+        Thread.handle_interrupt(Object => :never) do
+          @state = previous_state
+          operation.call
+        end
+      end
+    end
+  end
+end

data/lib/smith/budget/ledger_state.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Smith
+  module Budget
+    class LedgerState
+      attr_reader :consumed, :reserved
+
+      def initialize(consumed:, reserved:)
+        @consumed = amount_hash(consumed)
+        @reserved = amount_hash(reserved)
+        freeze
+      end
+
+      private
+
+      def amount_hash(amounts)
+        Hash.new(0).merge(amounts).freeze
+      end
+    end
+  end
+end

data/lib/smith/budget/ledger_state_transition.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "dry-initializer"
+require_relative "decimal_context"
+
+module Smith
+  module Budget
+    class LedgerStateTransition
+      extend Dry::Initializer
+
+      option :limits
+
+      def reserve(state, amounts)
+        DecimalContext.call do
+          amounts.each do |key, amount|
+            requested = state.consumed[key] + state.reserved[key] + amount
+            raise BudgetExceeded unless requested.finite? && requested <= limits.fetch(key)
+          end
+
+          LedgerState.new(consumed: state.consumed, reserved: add(state.reserved, amounts))
+        end
+      end
+
+      def reconcile(state, reserved_amounts, actuals)
+        DecimalContext.call do
+          LedgerState.new(
+            consumed: add(state.consumed, actuals),
+            reserved: subtract(state.reserved, reserved_amounts)
+          )
+        end
+      end
+
+      def release(state, reserved_amounts)
+        DecimalContext.call do
+          LedgerState.new(
+            consumed: state.consumed,
+            reserved: subtract(state.reserved, reserved_amounts)
+          )
+        end
+      end
+
+      def remaining(state, key)
+        DecimalContext.call do
+          amount = limits.fetch(key) - state.consumed[key] - state.reserved[key]
+          amount.negative? ? BigDecimal("0") : amount
+        end
+      end
+
+      private
+
+      def add(current, amounts)
+        merge(current, amounts) { |value, amount| value + amount }
+      end
+
+      def subtract(current, amounts)
+        merge(current, amounts) { |value, amount| value - amount }
+      end
+
+      def merge(current, amounts)
+        current.dup.tap do |result|
+          amounts.each do |key, amount|
+            value = yield(current.fetch(key, 0), amount)
+            raise ArgumentError, "budget state values must be non-negative" if value.negative?
+
+            result[key] = value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/smith/budget/public_state_validator.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  module Budget
+    class PublicStateValidator
+      extend Dry::Initializer
+
+      option :limits
+      option :representation
+      option :state_transition
+
+      def call(state)
+        representation.externalize(state.consumed)
+        representation.externalize(state.reserved)
+        limits.each_key do |dimension|
+          remaining = state_transition.remaining(state, dimension)
+          representation.externalize_amount(dimension, remaining)
+        end
+        state
+      end
+    end
+  end
+end

data/lib/smith/budget/reservation.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Smith
+  module Budget
+    class Reservation
+      attr_reader :amounts
+
+      def initialize(ledger_identity:, token:, amounts:)
+        @ledger_identity = ledger_identity
+        @token = token
+        @amounts = amounts.dup.freeze
+        freeze
+      end
+
+      def identity_for(ledger_identity)
+        @token if @ledger_identity.equal?(ledger_identity)
+      end
+    end
+  end
+end

data/lib/smith/budget/reservation_contract.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  module Budget
+    class ReservationContract
+      extend Dry::Initializer
+
+      option :ledger_identity
+
+      def token!(reservation)
+        validate_receipt!(reservation)
+        reservation.identity_for(ledger_identity) ||
+          raise(ArgumentError, "budget reservation belongs to another ledger")
+      end
+
+      def amounts!(reservation)
+        token!(reservation)
+        reservation.amounts
+      end
+
+      private
+
+      def validate_receipt!(reservation)
+        case reservation
+        when Reservation then return
+        end
+
+        raise ArgumentError, "budget settlement requires a reservation receipt"
+      end
+    end
+  end
+end

data/lib/smith/context/observation_masking.rb

@@ -11,7 +11,9 @@ module Smith
         window = strategy[:window]
         return messages unless window
 
-        system_msgs, non_system = messages.partition { |m| SYSTEM_ROLES.include?(m[:role]) }
+        system_msgs, non_system = messages.partition do |message|
+          SYSTEM_ROLES.include?(message[:role] || message["role"])
+        end
         system_msgs + non_system.last(window)
       end
     end

data/lib/smith/context/state_injection.rb

@@ -9,7 +9,7 @@ module Smith
         content = "#{MARKER}\n#{formatter.call(persisted)}"
 
         existing_index = messages.index do |message|
-          message_content = message[:content]
+          message_content = message[:content] || message["content"]
           message_content.is_a?(String) && message_content.start_with?(MARKER)
         end
 

data/lib/smith/doctor/checks/persistence_capabilities.rb

@@ -20,7 +20,7 @@ module Smith
           adapter = resolve_adapter
           return report_missing_adapter(report) if adapter.nil?
 
-          missing = OPTIONAL_CAPABILITIES.reject { |cap| Smith::PersistenceAdapters.supports?(adapter, cap) }
+          missing = OPTIONAL_CAPABILITIES.reject { |cap| capability_available?(adapter, cap) }
           return report_supported_capabilities(report, adapter) if missing.empty?
 
           report_missing_capabilities(report, adapter, missing)
@@ -32,6 +32,16 @@ module Smith
           nil
         end
 
+        def capability_available?(adapter, capability)
+          return false unless Smith::PersistenceAdapters.supports?(adapter, capability)
+          return true unless capability == :persistence_identity
+
+          identity = adapter.persistence_identity
+          identity.is_a?(String) && !identity.empty? && identity.bytesize <= 256
+        rescue StandardError
+          false
+        end
+
         def report_missing_adapter(report)
           report.add(
             name: "persistence.capabilities",
@@ -58,8 +68,13 @@ module Smith
             message: "#{adapter.class.name} missing optional capabilities: #{missing.join(", ")}",
             detail: "Smith will fall back where possible: non-versioned writes when store_versioned " \
                     "is missing, and payload updated_at parsing when heartbeat methods are missing. " \
-                    "Use RedisStore or Memory for full versioning and heartbeat coverage; " \
-                    "ActiveRecordStore currently covers optimistic locking when lock_version is present."
+                    "Without transaction_open? and transaction_identity, exact commit-aware " \
+                    "split-step confirmation is unavailable. " \
+                    "If transaction_open? returns true, transaction_identity is required and " \
+                    "split-step preparation fails before writing when it is missing. " \
+                    "Use RedisStore with an explicit persistence identity or Memory for full versioning " \
+                    "and heartbeat coverage; ActiveRecordStore covers optimistic locking and exact " \
+                    "transaction identity when configured with an identity."
           )
         end
       end

data/lib/smith/error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Smith
+  class Error < StandardError; end
+end