smith-agents 0.4.5 → 0.5.0

data/docs/PERSISTENCE.md

@@ -120,28 +120,112 @@ workflow.clear_persisted!("ticket:T-1042")
 
 These helpers do not make Smith a job system or durable runtime. They only remove repetitive restore/checkpoint boilerplate around the configured persistence adapter while leaving queueing, projection, and recovery policy with the host app.
 
+### Host-Coordinated Message Admission
+
+At a stable workflow boundary, a host can append one message or a bounded batch
+to the persisted session history:
+
+```ruby
+workflow = ReviewWorkflow.restore("ticket:T-1042", adapter: adapter)
+admission = workflow.append_session_messages!(
+  role: :user,
+  content: { answer: "The order id is 1042" }
+)
+
+workflow.persist!("ticket:T-1042", adapter: adapter)
+```
+
+Smith canonicalizes String and Symbol keys, owns an immutable JSON-like copy,
+appends the batch under the workflow lifecycle mutex, and returns an immutable
+`Smith::Workflow::MessageAdmission`. Its `message_digest` is the SHA-256 digest
+of the canonical message batch and can be correlated with host-owned evidence.
+
+Admission is bounded to 100 messages, 64 levels, 100,000 visited values, and one
+MiB of canonical JSON. Integers must fit a signed 64-bit value, Floats must be
+finite, Hash keys must be String or Symbol values, and cyclic or unsupported
+values fail closed. Work is `O(N + sum(K log K))`, where `N` is the number of
+visited values and each `K` is the key count of one Hash; retained output is
+`O(N)`.
+
+This API deliberately does not persist, resume, schedule, identify a session,
+or provide idempotency. A durable host must lock its run and checkpoint, verify
+the exact before identity, call admission, persist the next Smith version, and
+record its own cause and before/after evidence atomically. Calling the method
+while ordinary execution or a prepared split-step boundary is active is
+rejected.
+
 ### Host-Coordinated Step Boundaries
 
-Hosts can split one strict transition into explicit prepare, execute, and
-checkpoint phases:
+Hosts can split one strict transition into explicit prepare, optional exact
+dispatch claim, execution authorization, execute, and checkpoint phases:
 
 ```ruby
-transition_name = nil
+def execute_one_step(workflow, key, adapter)
+  transition_name = nil
+
+  ApplicationRecord.transaction do
+    transition_name = workflow.prepare_persisted_step!(key, adapter: adapter)
+    next unless transition_name
+
+    prepared = workflow.prepared_persisted_step
+    HostEvent.create!(
+      name: "step.started",
+      transition: transition_name,
+      operation_token: prepared.token,
+      preparation_digest: prepared.preparation_digest
+    )
+  end
 
-ApplicationRecord.transaction do
-  transition_name = workflow.prepare_persisted_step!(key, adapter: adapter)
-  HostEvent.create!(name: "step.started", transition: transition_name)
-end
+  return unless transition_name
+
+  workflow.confirm_prepared_step!
+
+  if workflow.class.definition_digest
+    dispatch = nil
+    ApplicationRecord.transaction do
+      dispatch = workflow.claim_prepared_step_dispatch!
+      HostAttempt.find_by!(operation_token: workflow.prepared_persisted_step.token)
+        .update!(
+          status: "dispatch_claimed",
+          dispatch_token: dispatch.token,
+          dispatch_receipt: dispatch.to_h
+        )
+    end
+    workflow.confirm_prepared_step_dispatch!
+  end
 
-workflow.confirm_prepared_step!
-step = workflow.execute_prepared_step! # provider/tool work; no host transaction
+  authorization = workflow.authorize_prepared_step_execution!
+  execution_started = false
+  begin
+    operation_token = authorization.prepared_step.token
+    dispatch_token = authorization.dispatch_claim&.token
+    start_status = dispatch_token ? "dispatch_claimed" : "prepared"
+    changed = ApplicationRecord.transaction do
+      HostAttempt.where(
+        operation_token:,
+        dispatch_token:,
+        status: start_status
+      ).update_all(status: "executing")
+    end
+    committed = HostAttempt.find_by(operation_token:, dispatch_token:)
+    execution_started = changed == 1 && committed&.status == "executing"
+    raise "host execution start did not commit exactly once" unless execution_started
+  ensure
+    workflow.release_prepared_step_execution!(authorization) unless execution_started
+  end
 
-ApplicationRecord.transaction do
-  workflow.persist!(key, adapter: adapter)
-  HostEvent.create!(name: "step.completed", transition: step.fetch(:transition))
-end
+  execution = workflow.execute_authorized_prepared_step!(authorization) # external work; no host transaction
+  raise execution.error if execution.failed?
+
+  step = execution.step
 
-workflow.complete_persisted_step!
+  ApplicationRecord.transaction do
+    workflow.persist!(key, adapter: adapter)
+    HostEvent.create!(name: "step.completed", transition: step.fetch(:transition))
+  end
+
+  workflow.complete_persisted_step!
+end
 ```
 
 This contract is available only to workflows using `idempotency_mode :strict`,
@@ -157,12 +241,134 @@ preparation. The key is copied into an immutable string and the transition
 contract is frozen. When an adapter can report an open transaction,
 `confirm_prepared_step!` must verify the committed preparation before execution;
 it refuses confirmation while that transaction is still open.
-`execute_prepared_step!` re-verifies the exact durable preparation and permits
-one execution attempt. Preparation also takes an O(S) defensive snapshot of
+After preparation, `prepared_persisted_step` returns an immutable
+`Smith::Workflow::PreparedStep` descriptor containing the opaque preparation
+token, transition and origin names, pinned persistence key and logical version,
+next step number, and canonical preparation-payload digest. It exposes no
+workflow context, messages, tool results, prompts, or provider output. The
+descriptor is a host correlation witness for
+the active process-local boundary, not a replacement checkpoint or authority to
+reconstruct and execute a workflow. Its scalar identity remains stable through
+execution and checkpointing. Use `prepared_persisted_step.to_h` when serializing
+the descriptor itself. It returns `nil` before persistence
+acknowledges preparation, after an ambiguous preparation outcome, when
+preparation begins on an already-terminal workflow, and after committed
+completion. With a transactional adapter, the
+descriptor is available inside the still-open transaction so the host can write
+its own correlated record atomically. The adapter's exact transaction identity
+is authoritative even when a host propagates that transaction context across
+fibers or executors. The descriptor is a correlation witness, not proof that the
+transaction subsequently committed.
+Use `Smith::Workflow::PreparedStep.deserialize` to restore a descriptor from a
+Hash or bounded JSON object. The decoder rejects missing, duplicated, and
+unknown attributes, and constrains persistence/step counters to positive signed
+64-bit values; direct `Dry::Struct` construction is not a transport decoder.
+
+For a workflow declaring `definition_digest`,
+`claim_prepared_step_dispatch!` atomically replaces the exact `prepared`
+payload with a `dispatching` payload through the adapter's `replace_exact`
+capability. The logical `persistence_version` does not change during this claim.
+Memory uses its monitor, Redis uses WATCH/MULTI/EXEC within the client's native
+no-reconnect scope, and Active Record uses one conditional SQL update while
+advancing its optimistic-lock column. The method
+performs no transition, provider, or tool work,
+so an Active Record host can commit its own attempt-ledger state in the same
+transaction without holding that transaction across external work. After that
+transaction commits, `confirm_prepared_step_dispatch!` verifies the exact
+durable claim. A rolled-back claim restores the known preparation; a missing,
+modified, concurrently claimed, or ambiguously acknowledged payload fails
+closed. `authorize_prepared_step_execution!` then re-verifies the exact durable
+claim and returns one process-local execution capability without performing
+transition, provider, or tool work. A host can commit its own `executing`
+attempt record after authorization and before external work. That host write
+must be a conditional compare-and-set on the exact dispatch identity, and the
+host must re-read committed database state after the outer transaction returns.
+An in-memory record or transaction return value is not commit evidence because
+Rails deliberately swallows `ActiveRecord::Rollback`. If the exact host state
+does not commit, the host must call `release_prepared_step_execution!` with the
+exact capability. `execute_authorized_prepared_step!` consumes it once and
+returns a `PreparedStepExecutionResult`. Its `status`, `failed?`, and `error`
+fields preserve transition failure independently of Smith failure routing; a
+host must not treat a failure-routed workflow state as proof that external work
+succeeded. The result owns an iterative, cycle-aware snapshot bounded to 128
+levels, 100,000 visited values, and 4 MiB of string data. Hashes, Arrays,
+Strings, finite scalar JSON-like values, String or Symbol Hash keys, and the
+exact top-level `StandardError` are supported; other values fail closed. Only the exact-payload
+winner may enter provider, tool, or deterministic step work. Smith snapshots
+and validates a successful step result before advancing workflow state. If the
+external call returns an unsupported or over-limit value, the validation error
+follows the transition's normal failure route and is returned as a typed failed
+result; the success destination is never committed.
+
+The authorization rejects copying and the standard Ruby Marshal, Psych/YAML,
+and JSON serialization hooks. It is bound by object identity to one workflow
+instance and by process id to the issuing Ruby process, so a forked child cannot
+consume inherited authority. It is not a lease, cross-process fence, or durable
+attempt receipt.
+Before consuming the capability, a host may inspect the exact captured agent
+bindings with a block:
+
+```ruby
+authorization.each_agent_binding do |registry_name, agent_class|
+  verify_host_execution_identity!(registry_name, agent_class)
+end
+```
+
+This bounded enumeration performs no provider or tool work and exposes the same
+classes Smith will execute. It is available only while the authorization is
+active in its issuing process. Calling it after release or consumption, from a
+forked process, or without a block fails closed. Smith intentionally does not
+return an `Enumerator`, because deferred iteration could outlive the capability
+scope. Smith first discovers binding names through a bounded graph traversal,
+then resolves the complete bounded set while holding one registry monitor epoch.
+Concurrent registry writes cannot split one authorization across old and new
+registry states. The registry-owned bulk capture reads concrete agent bindings
+without invoking lazy container callbacks, and all public registry mutation
+paths share the same monitor.
+
+While that authority is active, Smith's prepended subclass boundary dispatches
+private execution methods through the Smith-owned implementations captured by
+the runtime. This includes nested child workflows that inherit the same
+authorization. Ordinary workflow runs remain polymorphic and continue to honor
+subclass overrides; the membrane exists only for the authorized external-work
+boundary.
+Until the capability is consumed or released, the host must retain exclusive
+authority over that workflow recovery attempt. A process crash after the host
+commits `executing` is an unknown outcome for the host to reconcile; Smith does
+not infer that transition work did or did not begin.
+
+`execute_prepared_step!` remains the compatible one-call API. It internally
+authorizes and consumes the step and returns the legacy step Hash. Hosts that
+need a durable pre-dispatch attempt boundary should use the explicit
+authorization API instead.
+
+Active Record exact replacement is deliberately a low-level persistence write.
+It does not instantiate the model, run callbacks or validations, or update
+timestamp columns; the payload and locking columns must therefore be treated as
+infrastructure-owned state. Values still use Active Record type casting and
+serialization. This matches Rails' documented
+[`update_all`](https://api.rubyonrails.org/v8.1.1/classes/ActiveRecord/Relation.html#method-i-update_all)
+contract and keeps the comparison and replacement in one SQL statement.
+Smith supplies byte-exact predicates for PostgreSQL, SQLite, MySQL, and Trilogy
+Active Record adapters and fails closed before mutation on an unknown adapter.
+The payload column must be `text` or `string`; JSON/JSONB columns normalize
+representation and therefore cannot satisfy this byte-identity contract.
+
+The claim returns an immutable `Smith::Workflow::PreparedStepDispatch` receipt
+containing the prepared-step descriptor, an opaque dispatch token, and the
+canonical dispatch-payload digest. Persist `receipt.to_h` with the host attempt
+record. Use `PreparedStepDispatch.deserialize` for a bounded Hash/JSON transport
+round-trip; direct `Dry::Struct` construction is not a transport decoder.
+
+Preparation also takes an O(S) defensive snapshot of
 mutable workflow execution state, where S is the serialized state size. This
 is the necessary ownership boundary: aliases held before preparation cannot
 change what the accepted transition later consumes, and public mutable-state
 readers and `to_state` return defensive snapshots while the boundary is active.
+The canonical correlation digest is computed before dispatch in O(S log K)
+time, where K is the largest object-key count, and is bounded to 4 MiB and
+100,000 JSON nodes. Larger state must use Smith artifact references instead of
+an inline split-step payload.
 Subclass execution entry points remain guarded, and subclass TTL helpers cannot
 override the pinned boundary policy. The
 in-memory marker remains armed so any serialization
@@ -175,11 +381,115 @@ likewise refuses to run while the adapter reports an open transaction.
 `prepared_persisted_step?` exposes whether the one execution attempt remains
 available without revealing transition internals.
 
+#### Restart-Safe Prepared Recovery
+
+Cross-process recovery is opt-in. The workflow class must declare a lowercase
+SHA-256 `definition_digest` covering the complete executable definition:
+workflow topology, deterministic code assets, effective agents, prompts,
+models, tools, schemas, and guardrails. Smith validates this digest but does not
+derive it from Ruby reflection. `Proc#source_location` exposes only a filename
+and line, while `RubyVM::InstructionSequence` is MRI-specific,
+version-sensitive, and not portable across machines or Ruby versions. See the
+official [Proc documentation](https://docs.ruby-lang.org/en/master/Proc.html)
+and [InstructionSequence documentation](https://ruby-doc.org/3.2/RubyVM/InstructionSequence.html).
+
+```ruby
+class GeneratedWorkflow < Smith::Workflow
+  definition_digest signed_package.digest
+  idempotency_mode :strict
+  # states and transitions...
+end
+
+
+adapter = Smith::PersistenceAdapters::ActiveRecordStore.new(
+  model: WorkflowState,
+  identity: "primary:workflow-states"
+)
+
+descriptor = Smith::Workflow::PreparedStep.deserialize(host_receipt.fetch(:prepared_step))
+decision = Smith::Workflow::PreparedStepRecovery.not_started(descriptor)
+workflow = GeneratedWorkflow.recover_prepared_step(decision, adapter: adapter)
+dispatch = workflow.claim_prepared_step_dispatch!
+authorization = workflow.authorize_prepared_step_execution!
+# Conditionally commit the exact host attempt as executing and re-read it here.
+# Release the authorization unless the committed row proves that this worker
+# won; otherwise consume it outside the transaction.
+execution = workflow.execute_authorized_prepared_step!(authorization)
+
+# A replacement worker may continue a committed claim only when the host's
+# exclusive attempt ledger proves transition/provider/tool execution did not start.
+dispatch = Smith::Workflow::PreparedStepDispatch.deserialize(host_receipt.fetch(:dispatch_receipt))
+decision = Smith::Workflow::PreparedStepRecovery.not_started(dispatch)
+workflow = GeneratedWorkflow.recover_prepared_step(decision, adapter: adapter)
+authorization = workflow.authorize_prepared_step_execution!
+execution = workflow.execute_authorized_prepared_step!(authorization)
+```
+
+The host may construct `not_started` only after acquiring exclusive recovery
+authority and proving from its durable attempt ledger that provider/tool
+dispatch never started. Smith does not own leases, queues, attempt records, or
+that fact. Recovery performs one fetch, validates the exact canonical payload,
+class name, schema, definition digest, adapter identity, transition, origin,
+step number, token, key, and version, then reconstructs a guarded process-local
+boundary. It refuses an open adapter transaction and never migrates an
+in-progress payload. Ordinary `restore` remains fail-closed.
+
+Restart-safe preparation additionally requires a non-expiring adapter exposing
+both `replace_exact` and a stable, bounded `persistence_identity`. Configure the
+same non-secret identity for every process connected to one durable storage
+domain. Memory's generated identity is process-local and is suitable only for
+same-process tests. Cache adapters do not provide exact CAS and are unsupported
+for restart-safe prepared recovery.
+
+Recovery authorizes a payload already marked `dispatching` only when the host
+supplies the exact committed `PreparedStepDispatch` receipt and an explicit
+`not_started` decision. The host may make that decision only while holding
+exclusive recovery authority and after its durable attempt ledger proves that
+transition/provider/tool execution never started. Without that proof, a crash
+or lost acknowledgement after the exact claim has an uncertain external
+outcome. Smith never rewinds or executes it on its own.
+
+When claim and host-attempt writes share an Active Record transaction,
+`claim_prepared_step_dispatch!` leaves execution unavailable until
+`confirm_prepared_step_dispatch!` runs after commit. A rollback restores the
+known prepared boundary and permits a new exact claim. Any other confirmation
+result remains uncertain and cannot execute.
+
+The definition digest is pinned and sealed on the class object when preparation
+or recovery authority is acquired. A concurrent DSL setter either completes
+before sealing and becomes the pinned identity, or raises before claim and
+execution. Repeating the same digest remains idempotent. A reloaded definition
+must use a new class object; recovery through that class still validates its
+digest against the durable descriptor.
+
+Exact replacement is a current-value compare-and-swap, not a historical fencing
+ledger. A restart-safe workflow key must be exclusively owned by Smith's
+versioned/exact persistence path. Hosts must not call unconditional `store`,
+delete/recreate the key, or restore an earlier byte-identical payload while a
+boundary is active. Such an out-of-band A-to-B-to-A rewrite is
+information-theoretically indistinguishable from the original value without a
+separate monotonic storage generation. Hosts that permit other writers must
+fence them in their own durable attempt/storage ledger; Smith does not absorb
+that host policy.
+
+Redis versioned and exact CAS require a client-native reconnect-disabling
+scope around WATCH/MULTI/EXEC. redis-rb 5.4 exposes `without_reconnect`, while
+newer clients may expose `disable_reconnection`; Smith accepts either and
+refuses CAS before WATCH when neither exists. This follows redis-rb's official
+[reconnection contract](https://github.com/redis/redis-rb#reconnections) and
+prevents a transaction from being replayed after connection-scoped WATCH state
+has been lost.
+
 Workflow classes are part of the execution contract once preparation begins.
 Hosts must not add or prepend methods to that class until the boundary is
-complete, and custom `inherited` hooks must call `super`. Ruby intentionally
-allows open-class mutation, so Smith treats post-preparation class mutation as
-an unsupported host lifecycle violation rather than attempting to sandbox it.
+complete, and custom `inherited` hooks must call `super`. The same rule applies
+to reachable nested workflow and captured agent classes. Smith captures and
+revalidates nested transition contracts and exact agent class bindings, while a
+host must not concurrently mutate those class objects. Ruby intentionally
+allows open-class mutation. Smith blocks definition-digest changes after the
+class is sealed, while other post-preparation class mutation remains an
+unsupported host lifecycle violation rather than something Smith attempts to
+sandbox.
 
 The lifecycle row and Smith checkpoint are atomic only when the persistence
 adapter participates in the same transaction and database connection domain as
@@ -189,8 +499,11 @@ cannot confirm an uncommitted boundary. Memory, Redis, cache-backed,
 cross-database, and external adapters do not participate in
 `ApplicationRecord.transaction`; hosts using them must supply their own
 coordination protocol and must not claim the two writes are atomic.
-Custom transactional adapters should implement `transaction_open?` so Smith can
-enforce the same commit-aware confirmation rule.
+Custom transactional adapters should implement both `transaction_open?` and
+`transaction_identity`. The identity must be stable for one open transaction or
+savepoint and change for every later transaction. Smith's `ActiveRecordStore`
+uses the public `current_transaction.uuid` API for this exact fence. Smith fails
+before writing when an open transaction has no exact identity capability.
 
 If execution raises or the process dies after external work, the durable marker
 remains set. A strict restore therefore fails closed with
@@ -248,7 +561,7 @@ standard optimistic-locking column:
 ```ruby
 create_table :workflow_states do |t|
   t.string :key, null: false, index: { unique: true }
-  t.jsonb :payload, null: false
+  t.text :payload, null: false
   t.integer :lock_version, null: false, default: 0
   t.timestamps
 end
@@ -258,7 +571,10 @@ end
 
 Smith.configure do |config|
   config.persistence_adapter = :active_record
-  config.persistence_options = { model: WorkflowState }
+  config.persistence_options = {
+    model: WorkflowState,
+    identity: "primary:workflow-states"
+  }
 end
 ```
 
@@ -283,8 +599,14 @@ Smith.configure do |config|
 end
 ```
 
-The unique key must be enforced by the database. Initial creation uses Rails'
-native `create_or_find_by!` savepoint path, so a concurrent key insert does not
+The unique key must be enforced by the database. Before every exact write,
+Smith verifies from database metadata that the configured key is the database
+primary key or has its own unconditional single-column unique index. Model-only
+primary-key declarations, partial indexes, and composite indexes are not
+accepted. Smith uses Active Record's table-keyed schema cache; a cold check is
+`O(I)` in the table's index count and never scans workflow rows. Initial
+creation uses Rails' native
+`create_or_find_by!` savepoint path, so a concurrent key insert does not
 invalidate a PostgreSQL caller transaction. A collision on another unique
 constraint is not misreported as a key-version conflict.
 

data/lib/smith/agent/lifecycle.rb

@@ -21,9 +21,9 @@ module Smith
         instance.after_completion(result, context)
       end
 
-      def invoke_agent(agent_class, prepared_input)
+      def invoke_agent(agent_class, prepared_input, output_schema: agent_class.output_schema)
         check_deadline!
-        response, model_used = complete_with_provider(agent_class, prepared_input)
+        response, model_used = complete_with_provider(agent_class, prepared_input, output_schema:)
         snapshot_and_finalize(agent_class, response, model_used)
       end
 
@@ -33,12 +33,12 @@ module Smith
       # parallel fan-out, two branches sharing the workflow could race
       # and attribute the wrong model to the wrong response. Local data
       # eliminates the race entirely.
-      def complete_with_provider(agent_class, prepared_input)
+      def complete_with_provider(agent_class, prepared_input, output_schema:)
         models = build_model_chain(agent_class)
 
         models.each_with_index do |model_id, index|
           check_deadline! if index.positive?
-          response = attempt_model(agent_class, prepared_input, model_id)
+          response = attempt_model(agent_class, prepared_input, model_id, output_schema:)
           return [response, model_id]
         rescue Smith::Error
           raise
@@ -71,10 +71,10 @@ module Smith
               "model block for #{agent_class} must return a non-empty string; got #{result.inspect}"
       end
 
-      def attempt_model(agent_class, prepared_input, model_id)
+      def attempt_model(agent_class, prepared_input, model_id, output_schema:)
         chat = agent_class.chat(model: model_id, **bridge_workflow_inputs(agent_class))
         add_prepared_input(chat, prepared_input)
-        chat = chat.with_schema(agent_class.output_schema) if agent_class.output_schema
+        chat = chat.with_schema(output_schema) if output_schema
         chat.complete
       end
 
@@ -121,7 +121,7 @@ module Smith
         end
 
         merge_system_messages!(chat, system_messages) if system_messages.any?
-        other_messages.each { |message| chat.add_message(message) }
+        other_messages.each { |message| add_message(chat, message) }
       end
 
       def provider_safe_prepared_input(prepared_input)
@@ -141,7 +141,7 @@ module Smith
       end
 
       def merge_system_messages!(chat, prepared_system_messages)
-        return prepared_system_messages.each { |message| chat.add_message(message) } unless chat.respond_to?(:messages)
+        return prepared_system_messages.each { |message| add_message(chat, message) } unless chat.respond_to?(:messages)
 
         existing_system_contents = chat.messages.filter_map do |message|
           message.content if message_role(message) == :system
@@ -153,16 +153,25 @@ module Smith
         combined_contents = existing_system_contents + prepared_system_contents
         return if combined_contents.empty?
         unless combined_contents.all?(String)
-          return prepared_system_messages.each { |message| chat.add_message(message) }
+          return prepared_system_messages.each { |message| add_message(chat, message) }
         end
 
         if chat.respond_to?(:with_instructions)
           chat.with_instructions(combined_contents.join("\n\n"))
         else
-          prepared_system_messages.each { |message| chat.add_message(message) }
+          prepared_system_messages.each { |message| add_message(chat, message) }
         end
       end
 
+      def add_message(chat, message)
+        attributes = if message.is_a?(Hash)
+                       message.transform_keys { |key| key.respond_to?(:to_sym) ? key.to_sym : key }
+                     else
+                       message
+                     end
+        chat.add_message(attributes)
+      end
+
       def message_role(message)
         message_attribute(message, :role)&.to_sym
       end

data/lib/smith/agent/registry/execution_binding_capture.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Smith
+  class Agent
+    module Registry
+      module ExecutionBindingCapture
+        def capture_bindings!(requests)
+          registry_monitor.synchronize do
+            requests.each_with_object({}) do |request, bindings|
+              key = normalize_key(request.fetch(:name))
+              binding = binding_for(key)
+              klass = binding&.fetch(:agent_class, nil)
+              unless klass
+                raise Smith::WorkflowError,
+                      "unresolved #{request.fetch(:role)} :#{key}" \
+                      "#{fetch_suffix(request.fetch(:workflow_class), request.fetch(:transition_name))}"
+              end
+
+              bindings[key] = klass
+            end.freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/smith/agent/registry/mutation_boundary.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Smith
+  class Agent
+    module Registry
+      module MutationBoundary
+        def merge(...)
+          registry_monitor.synchronize { super }
+        end
+
+        def decorate(...)
+          registry_monitor.synchronize { super }
+        end
+
+        def namespace(...)
+          registry_monitor.synchronize { super }
+        end
+
+        def import(...)
+          registry_monitor.synchronize { super }
+        end
+
+        def configure(...)
+          registry_monitor.synchronize { super }
+        end
+      end
+    end
+  end
+end

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.