little_ghost 0.3.0 → 0.4.0

data/lib/little_ghost/run.rb

@@ -12,30 +12,68 @@ module LittleGhost
   #   run.outcome    # => "completed"
   #   run.response   # => "Transfer 481 is waiting for the receiving bank."
   #
-  # The class-level ask helper[rdoc-ref:LittleGhost::Assembly.ask] or standalone
-  # ask method[rdoc-ref:LittleGhost::Assembly#ask] consumes the event stream and
-  # returns the Run. For a live interface, the class-level streaming
+  # The class-level ask helper[rdoc-ref:LittleGhost::Assembly.ask] and standalone
+  # ask method[rdoc-ref:LittleGhost::Assembly#ask] return the Run after work
+  # finishes. For a live interface, use the class-level streaming
   # helper[rdoc-ref:LittleGhost::Assembly.stream_ask] or standalone streaming
-  # method[rdoc-ref:LittleGhost::Assembly#stream_ask] yields StreamEvent objects
-  # and returns the same run after enumeration. A run can execute only once.
+  # method[rdoc-ref:LittleGhost::Assembly#stream_ask]. The stream yields
+  # StreamEvent objects, and enumeration returns the same Run with its final
+  # outcome and response. A Run executes only once.
+  #
+  #   stream = CustomerSupportAgent.stream_ask("Where is transfer 481?")
+  #   run = stream.each do |event|
+  #     publish(event) if event.type == :text_delta
+  #   end
+  #
+  #   run.completed? # => true
+  #   run.response
   #
   # Completion, failure, deadline, and cancellation become the +completed+,
   # +failed+, +partial+, and +cancelled+ outcomes. Ordinary execution failures
-  # are available through +error+ and the terminal stream event; cleanup, event
-  # delivery, or instrumentation failures may still raise because the framework
-  # cannot safely report a clean stop.
+  # are available through +error+ and the terminal stream event. Failures while
+  # closing resources, delivering events, or reporting instrumentation may
+  # still raise because LittleGhost cannot report a reliable ending.
+  #
+  # Tool validation and ToolError failures return safe Tool results to the model,
+  # which may recover and complete the Run. Input, configuration, or resource
+  # construction can raise before a Run exists. Once execution begins, terminal
+  # events are +run_stop+, +run_error+, +run_partial+, and +run_cancel+.
   #
-  # The run opens its workspace, sandbox, session, and assembly entrypoint, then closes
-  # registered resources in reverse order. +register+ extends that lifecycle for
-  # application resources. Interruption is available only while an agent
-  # entrypoint is active and unambiguous.
+  # The Run opens its workspace, sandbox, Session, and Assembly entrypoint, then
+  # closes registered resources in reverse order. +register+ adds application
+  # resources to that lifecycle. Interjection is available only while one Agent
+  # entrypoint is active.
   class Run
     include Enumerable
 
-    # Runtime and declarations used to execute the run; its request, cancellation
-    # token, resources, terminal outcome, response, result, usage, and error.
-    attr_reader :runtime, :agent_class, :entrypoint_class, :invocation, :cancellation_token, :result, :operation_id,
-      :outcome, :response, :error, :session, :usage, :workspace, :sandbox
+    # Runtime that built and executes this Run.
+    attr_reader :runtime
+    # Agent class used for compatibility when the entrypoint is an Agent.
+    attr_reader :agent_class
+    # Public Agent, Workflow, Swarm, or Graph class selected by the caller.
+    attr_reader :entrypoint_class
+    # Normalized request carried by this Run.
+    attr_reader :invocation
+    # Token that cooperatively stops this Run and its children.
+    attr_reader :cancellation_token
+    # Final RunResult, when the Assembly produced one.
+    attr_reader :result
+    # Unique identifier for this top-level operation.
+    attr_reader :operation_id
+    # Terminal String: +completed+, +failed+, +partial+, or +cancelled+.
+    attr_reader :outcome
+    # Caller-facing final text, or the partial text preserved at a deadline.
+    attr_reader :response
+    # Exception that caused a failed, partial, or cancelled outcome.
+    attr_reader :error
+    # Session opened for this invocation, when persistence is configured.
+    attr_reader :session
+    # Normalized Usage accumulated by the Run.
+    attr_reader :usage
+    # Request-scoped workspace owned or supplied by the Run.
+    attr_reader :workspace
+    # Request-scoped sandbox owned or supplied by the Run.
+    attr_reader :sandbox
 
     # Creates a dormant run for +invocation+.
     def initialize(invocation:, runtime:, agent_class: nil, assembly_class: nil, entrypoint_class: nil,
@@ -66,10 +104,10 @@ module LittleGhost
       @exclusive_tools_mutex = Mutex.new
       @once_mutex = Mutex.new
       @once_keys = {}
-      @interruption_mutex = Mutex.new
-      @interruption_condition = ConditionVariable.new
-      @interruption_state = :not_started
-      @active_interruptions = 0
+      @interjection_mutex = Mutex.new
+      @interjection_condition = ConditionVariable.new
+      @interjection_state = :not_started
+      @active_interjections = 0
       @entrypoint = nil
       @usage = Usage.new
     end
@@ -108,23 +146,23 @@ module LittleGhost
     # True when cancellation stopped the run without a response.
     def cancelled? = outcome == "cancelled"
 
-    # Adds an interruption to the active entrypoint and waits for its response.
+    # Adds an interjection to the active entrypoint and waits for its response.
     #
-    # Raises LittleGhost::AgentInterruptError before the entrypoint is ready,
-    # after it finishes, or when the entrypoint does not support interruptions.
-    def interrupt_response(
+    # Raises LittleGhost::AgentInterjectionError before the entrypoint is ready,
+    # after it finishes, or when the entrypoint does not support interjections.
+    def interject(
       message,
-      interruption_id: nil,
+      interjection_id: nil,
       batch_key: nil,
       metadata: {},
       cancellation_token: Support::CancellationToken.new,
       deadline: nil
     )
-      interrupt_response_with do
+      interject_with do
         [
           message,
           {
-            interruption_id:,
+            interjection_id:,
             batch_key:,
             metadata:,
             cancellation_token:,
@@ -134,29 +172,29 @@ module LittleGhost
       end
     end
 
-    def interrupt_response_with # :nodoc:
-      entrypoint = @interruption_mutex.synchronize do
-        case @interruption_state
+    def interject_with # :nodoc:
+      entrypoint = @interjection_mutex.synchronize do
+        case @interjection_state
         when :not_started, :starting
-          raise AgentInterruptError, "Run entrypoint is not ready for interruptions"
+          raise AgentInterjectionError, "Run entrypoint is not ready for interjections"
         when :terminal
-          raise AgentInterruptError, "Run has already finished"
+          raise AgentInterjectionError, "Run has already finished"
         end
 
-        @active_interruptions += 1
+        @active_interjections += 1
         @entrypoint
       end
-      unless entrypoint.respond_to?(:interrupt_response)
-        raise AgentInterruptError, "Run entrypoint does not support interruptions"
+      unless entrypoint.respond_to?(:interject)
+        raise AgentInterjectionError, "Run entrypoint does not support interjections"
       end
 
       message, options = yield
-      entrypoint.interrupt_response(message, **options)
+      entrypoint.interject(message, **options)
     ensure
       if entrypoint
-        @interruption_mutex.synchronize do
-          @active_interruptions -= 1
-          @interruption_condition.broadcast
+        @interjection_mutex.synchronize do
+          @active_interjections -= 1
+          @interjection_condition.broadcast
         end
       end
     end
@@ -210,8 +248,8 @@ module LittleGhost
       end
     end
 
-    def prepare_interruption(payload) # :nodoc:
-      runtime.prepare_interruption(self, payload)
+    def prepare_interjection(payload) # :nodoc:
+      runtime.prepare_interjection(self, payload)
     end
 
     # Closes registered resources in reverse order.
@@ -273,7 +311,7 @@ module LittleGhost
       sandbox&.open(run: self)
       @session = runtime.open_session(self)
       agent = runtime.build_assembly(@execution_class, run: self)
-      @interruption_mutex.synchronize do
+      @interjection_mutex.synchronize do
         @entrypoint = agent
       end
       register(agent)
@@ -294,11 +332,11 @@ module LittleGhost
           end
         }
         if agent.is_a?(Agent)
-          options[:interrupt_ready] = lambda do
-            @interruption_mutex.synchronize { @interruption_state = :active }
+          options[:interject_ready] = lambda do
+            @interjection_mutex.synchronize { @interjection_state = :active }
           end
         else
-          @interruption_mutex.synchronize { @interruption_state = :active }
+          @interjection_mutex.synchronize { @interjection_state = :active }
         end
 
         agent.stream(invocation.message, **options).each do |event|
@@ -359,9 +397,9 @@ module LittleGhost
         }
       ]
     ensure
-      @interruption_mutex.synchronize do
-        @interruption_state = :terminal
-        @interruption_condition.wait(@interruption_mutex) while @active_interruptions.positive?
+      @interjection_mutex.synchronize do
+        @interjection_state = :terminal
+        @interjection_condition.wait(@interjection_mutex) while @active_interjections.positive?
         @last_entrypoint = @entrypoint
         @entrypoint = nil
       end
@@ -631,7 +669,7 @@ module LittleGhost
         raise Error, "run has already started" if @started
         @started = true
       end
-      @interruption_mutex.synchronize { @interruption_state = :starting }
+      @interjection_mutex.synchronize { @interjection_state = :starting }
     end
 
     def close_callback(resource)

data/lib/little_ghost/run_context.rb

@@ -9,12 +9,25 @@ module LittleGhost
   # cancellation and deadlines, checkpoint messages, and accumulate usage.
   # Access to framework-managed fields is thread-safe.
   class RunContext
-    # Shared state, cancellation, deadline, metadata, operation identity, and
-    # durable conversation identity for the current work.
-    attr_reader :state, :cancellation_token, :deadline, :metadata,
-      :agent_operation_id, :conversation_id
-
-    # Creates a context with optional checkpoint and interruption state.
+    # Mutable DataMap state supplied to this invocation. A top-level Run starts
+    # with restored Session state merged with current Invocation context; child
+    # Assemblies may receive copied, mapped, or empty state. Application code must
+    # synchronize mutations when parallel Tools share this map, or use exclusive
+    # Tools. String and Symbol keys address the same value; persisted snapshots
+    # use canonical String keys.
+    attr_reader :state
+    # Token used to cooperatively stop the current work.
+    attr_reader :cancellation_token
+    # Wall-clock deadline for the current work, when present.
+    attr_reader :deadline
+    # Framework metadata attached to this context.
+    attr_reader :metadata
+    # Active Agent operation identifier, after the context is bound.
+    attr_reader :agent_operation_id
+    # Durable subagent conversation identifier, when present.
+    attr_reader :conversation_id
+
+    # Creates a context with optional checkpoint and interjection state.
     def initialize(
       state: {},
       cancellation_token: Support::CancellationToken.new,
@@ -22,15 +35,15 @@ module LittleGhost
       metadata: {},
       checkpoint: nil,
       conversation_id: nil,
-      interruption_metadata: nil,
-      interruption_ids: []
+      interjection_metadata: nil,
+      interjection_ids: []
     )
       if conversation_id
         conversation_id = String(conversation_id)
         raise ArgumentError, "conversation_id cannot be empty" if conversation_id.empty?
         conversation_id = conversation_id.dup.freeze
       end
-      @state = state
+      @state = DataMap.new(state)
       @cancellation_token = cancellation_token
       @deadline = deadline
       @metadata = metadata.freeze
@@ -42,9 +55,9 @@ module LittleGhost
       @structured_result_mutex = Mutex.new
       @agent_operation_id = nil
       @agent_operation_id_mutex = Mutex.new
-      @interruption_mutex = Mutex.new
-      @interruption_metadata = interruption_metadata&.to_h
-      @interruption_ids = Array(interruption_ids).map { |id| String(id).dup.freeze }.freeze
+      @interjection_mutex = Mutex.new
+      @interjection_metadata = interjection_metadata&.to_h
+      @interjection_ids = Array(interjection_ids).map { |id| String(id).dup.freeze }.freeze
     end
 
     # Raises LittleGhost::CancelledError or LittleGhost::DeadlineExceededError
@@ -99,20 +112,20 @@ module LittleGhost
       @structured_result_mutex.synchronize { @structured_result }
     end
 
-    def interruption_metadata # :nodoc:
-      @interruption_mutex.synchronize { @interruption_metadata }
+    def interjection_metadata # :nodoc:
+      @interjection_mutex.synchronize { @interjection_metadata }
     end
 
-    def interruption_ids # :nodoc:
-      @interruption_mutex.synchronize { @interruption_ids }
+    def interjection_ids # :nodoc:
+      @interjection_mutex.synchronize { @interjection_ids }
     end
 
-    def activate_interruption(metadata:, ids:) # :nodoc:
+    def activate_interjection(metadata:, ids:) # :nodoc:
       value = metadata&.to_h
       values = Array(ids).map { |id| String(id).dup.freeze }.freeze
-      @interruption_mutex.synchronize do
-        @interruption_metadata = value
-        @interruption_ids = values
+      @interjection_mutex.synchronize do
+        @interjection_metadata = value
+        @interjection_ids = values
       end
     end
 

data/lib/little_ghost/runtime/hook.rb

@@ -3,7 +3,7 @@
 module LittleGhost
   class Runtime
     # Hooks let applications prepare runs, select session history, transform
-    # interruptions, and map errors to caller-safe messages.
+    # interjections, and map errors to caller-safe messages.
     #
     # Hooks are instantiated once per Runtime in configuration order. Override
     # only the methods needed and return the supplied value when leaving it
@@ -20,8 +20,8 @@ module LittleGhost
       # lifecycle and close in reverse order.
       def prepare_run(run) = run
 
-      # Transforms an interruption payload before it reaches the agent.
-      def prepare_interruption(_run, payload) = payload
+      # Transforms an interjection payload before it reaches the agent.
+      def prepare_interjection(_run, payload) = payload
 
       # Returns the history to use for this run, or nil to defer to later hooks
       # and the session default. +stored+ is empty when the session is new;

data/lib/little_ghost/runtime.rb

@@ -4,45 +4,86 @@ require "json"
 require_relative "configuration"
 
 module LittleGhost
-  # Prepare the shared services that assemblies use across many runs.
-  # A runtime owns model resolution, loading, persistence, lookup paths, hooks,
-  # and resource factories for one Ruby setup.
+  # Owns the shared services that assemblies reuse across many Runs.
+  #
+  # Most applications do not construct this class. Configure LittleGhost once
+  # and call a named Agent or Assembly; the first standalone call lazily builds
+  # +LittleGhost.runtime+, and later calls reuse it automatically. Each call
+  # still receives a fresh Run, bound participants, Tools, workspace, and
+  # sandbox.
+  #
+  # Construct Runtime directly when one process intentionally hosts an isolated
+  # LittleGhost setup:
   #
   #   configuration = LittleGhost::Configuration.new(
   #     root: Dir.pwd,
   #     providers: {
-  #       openai: {adapter: :openai, api_key: ENV.fetch("OPENAI_API_KEY")}
+  #       openrouter: {adapter: :openrouter, api_key: ENV.fetch("OPENROUTER_API_KEY")}
   #     },
-  #     models: {customer_support: {target: "openai:gpt-5.6-luna"}},
-  #     default_model: "customer_support",
+  #     models: {customer_support: {target: "openrouter:openai/gpt-5.6-luna"}},
+  #     default_model: :customer_support,
   #     service_name: "support-api"
   #   )
   #   runtime = LittleGhost::Runtime.new(configuration: configuration)
   #
-  #   runtime.service_name # => "support-api"
-  #   runtime.root == Pathname.new(File.realpath(Dir.pwd)) # => true
+  #   CustomerSupportAgent.new(runtime: runtime)
+  #     .ask("Where is order 481?")
+  #     .response
+  #
+  # Explicit construction snapshots the supplied Configuration but does not
+  # replace LittleGhost's shared default Runtime.
+  #
+  # A Runtime may build independent Runs concurrently. Each Run gets its own
+  # bound participants and Tools. By default, Runtime also creates a workspace
+  # and sandbox owned by that Run. Existing workspace or sandbox instances
+  # passed by the application remain caller-owned. Other supplied objects may
+  # receive calls from several threads, so custom stores, resolvers, hooks,
+  # subscribers, providers, and resource factories must be thread-safe. One
+  # SessionStore instance serializes calls sharing a Session; multi-process
+  # deployments need coordination provided by their store.
+  #
+  # == Advanced construction and ownership
   #
-  # Without explicit +settings+, construction canonicalizes the root, loads
-  # +config/little_ghost.rb+ once through the Configuration, snapshots settings,
-  # configures instrumentation, eager-loads application constants, and builds the
-  # selected model resolver and session store. Supplying +settings+ is the
-  # lower-level path used to create a sibling runtime from an existing snapshot.
+  # Normal construction reads the application's configured definitions and
+  # builds shared model resolution, persistence, hooks, and resource factories.
+  # The +settings+ form and #build are lower-level extension points for deriving
+  # another Runtime from an existing configuration snapshot.
   #
-  # Reuse a runtime across runs. +build_run+ creates any missing workspace and
-  # sandbox, transfers ownership only after both are built, and closes partial
-  # resources if construction fails. +build+ creates a sibling with explicit
-  # overrides and reuses the loader only when the application root is unchanged.
+  # #build_run creates a workspace and sandbox when needed. Once the Run owns
+  # them, it closes them; if construction stops halfway through, Runtime closes
+  # the partial resources. Startup failures are reported to instrumentation and
+  # then raised. Session actor resolution must use authenticated application
+  # identity. The default UnrestrictedSandbox uses host permissions and is not a
+  # security boundary for untrusted work.
   #
-  # Startup emits structured lifecycle instrumentation; a failed phase emits a
-  # failure event, flushes instrumentation, and re-raises the original exception.
-  # Session actor resolution must use trusted authenticated identity for tenant
-  # isolation. The default UnrestrictedSandbox is convenient application plumbing,
-  # not a security boundary for untrusted work.
+  # Runtime has no shutdown operation. Runs close resources created for their
+  # request. The application shuts down shared services and process-wide
+  # Instrumentation subscribers with the rest of the process.
   class Runtime
-    # The snapshotted setup and materialized services used by new runs.
-    attr_reader :configuration, :settings, :root, :loader, :prompt_paths, :skill_paths,
-      :skill_resource_root, :model_resolver, :session_store, :workspace_class, :sandbox_class,
-      :runtime_hooks
+    # Configuration object used to construct this Runtime.
+    attr_reader :configuration
+    # Settings snapshot used by new Runs.
+    attr_reader :settings
+    # Canonical application root.
+    attr_reader :root
+    # Loader used for conventional application definitions.
+    attr_reader :loader
+    # Ordered directories searched for prompt templates.
+    attr_reader :prompt_paths
+    # Ordered directories searched for skill definitions.
+    attr_reader :skill_paths
+    # Root used for skill-owned resources, when configured.
+    attr_reader :skill_resource_root
+    # Resolver that turns model roles and targets into executable Models.
+    attr_reader :model_resolver
+    # Shared store used to open per-Run Sessions.
+    attr_reader :session_store
+    # Configured Workspace implementation, or +nil+ for the default.
+    attr_reader :workspace_class
+    # Configured Sandbox implementation, or +nil+ for the default.
+    attr_reader :sandbox_class
+    # Runtime hooks called around request and session preparation.
+    attr_reader :runtime_hooks
 
     # Starts a runtime from +configuration+ or an existing settings snapshot.
     def initialize(configuration:, settings: nil)
@@ -129,8 +170,7 @@ module LittleGhost
       payload.is_a?(@invocation_class) ? payload : @invocation_class.new(payload)
     end
 
-    # Creates a Run and transfers ownership of newly created workspace and
-    # sandbox resources to it.
+    # Creates a Run that owns any workspace and sandbox built for the request.
     def build_run(
       payload,
       agent_class: nil,
@@ -230,7 +270,7 @@ module LittleGhost
       assembly_class_or_name.new(run:, runtime: self)
     end
 
-    # The low-cardinality service name attached to runtime telemetry.
+    # The stable service name attached to runtime telemetry.
     def service_name
       @settings&.[](:service_name) || default_service_name
     end
@@ -264,9 +304,9 @@ module LittleGhost
       run
     end
 
-    def prepare_interruption(run, payload) # :nodoc:
+    def prepare_interjection(run, payload) # :nodoc:
       runtime_hooks.reduce(payload) do |prepared, hook|
-        hook.prepare_interruption(run, prepared)
+        hook.prepare_interjection(run, prepared)
       end
     end
 

data/lib/little_ghost/session.rb

@@ -21,7 +21,7 @@ module LittleGhost
   #     store: session.store
   #   )
   #   reopened.history.last.text # => "Hello"
-  #   reopened.state              # => {language: "en"}
+  #   reopened.state[:language]  # => "en"
   #
   # === Persistence and trust
   #
@@ -43,7 +43,7 @@ module LittleGhost
       @actor_id = actor_id&.to_s
       @store = store
       @operation_id = operation_id
-      @metadata = metadata.to_h.freeze
+      @metadata = DataMap.new(metadata).freeze
       @loaded = false
     end
 
@@ -63,16 +63,18 @@ module LittleGhost
       load&.fetch(:messages) || fallback
     end
 
-    # Exposes a mutable copy of the persisted application state.
+    # Exposes a mutable DataMap copy of the persisted application state. String
+    # and Symbol keys address the same value; persisted snapshots use Strings.
     def state
       snapshot = load
-      snapshot ? mutable_copy(snapshot.fetch(:state)) : {}
+      DataMap.new(snapshot ? snapshot.fetch(:state) : {})
     end
 
     # Uses persisted metadata when present and otherwise keeps the metadata from
-    # construction.
+    # construction. The returned DataMap is frozen.
     def metadata
-      load&.fetch(:metadata) || @metadata
+      loaded = load
+      loaded ? DataMap.new(loaded.fetch(:metadata)).freeze : @metadata
     end
 
     # Atomically appends +messages+ when the store still has the expected
@@ -165,8 +167,8 @@ module LittleGhost
     def build_snapshot(messages:, state:, metadata:)
       {
         messages: persistable_messages(messages),
-        state: Support.deep_dup(state.to_h),
-        metadata: Support.deep_dup(metadata.to_h)
+        state: DataMap.new(state).to_h,
+        metadata: DataMap.new(metadata).to_h
       }.freeze
     end
 
@@ -193,8 +195,8 @@ module LittleGhost
 
       {
         messages: persistable_messages(Array(value.fetch(:messages))),
-        state: Support.deep_dup(value.fetch(:state, {}).to_h),
-        metadata: Support.deep_dup(value.fetch(:metadata, {}).to_h)
+        state: DataMap.new(value.fetch(:state, {})).to_h,
+        metadata: DataMap.new(value.fetch(:metadata, {})).to_h
       }.freeze
     rescue KeyError, NoMethodError, TypeError => error
       raise ProtocolError, "Session store returned an invalid value: #{error.class}"
@@ -212,18 +214,5 @@ module LittleGhost
         sanitized
       end.freeze
     end
-
-    def mutable_copy(value)
-      case value
-      when Hash
-        value.to_h { |key, child| [mutable_copy(key), mutable_copy(child)] }
-      when Array
-        value.map { |child| mutable_copy(child) }
-      when String
-        value.dup
-      else
-        value
-      end
-    end
   end
 end

data/lib/little_ghost/session_store.rb

@@ -21,9 +21,11 @@ module LittleGhost
   #     end
   #   end
   #
-  # A snapshot contains +:messages+, +:state+, and +:metadata+. Implementations
-  # provide #load, #append, and #replace; #append must check +expected_count+
-  # atomically so two writers cannot silently lose a turn.
+  # A snapshot contains +:messages+, +:state+, and +:metadata+. State and
+  # metadata cross this boundary as deeply string-keyed JSON mappings. Sessions
+  # expose the same data through DataMap, which accepts String or Symbol keys.
+  # Implementations provide #load, #append, and #replace; #append must check
+  # +expected_count+ atomically so two writers cannot silently lose a turn.
   #
   # Actor identity always comes from the caller. A store must not infer it from
   # ambient process state.
@@ -39,14 +41,16 @@ module LittleGhost
       raise AbstractMethodError, "#{self.class} must implement #load"
     end
 
-    # Atomically appends sanitized messages and stores state and metadata.
+    # Atomically appends sanitized messages and stores canonical JSON state and
+    # metadata.
     # Implementations raise ProtocolError if the persisted message count differs
     # from +expected_count+.
     def append(_id, messages:, state:, metadata:, expected_count:, actor_id: nil)
       raise AbstractMethodError, "#{self.class} must implement #append"
     end
 
-    # Replaces the complete snapshot for +id+ atomically.
+    # Replaces the complete snapshot for +id+ atomically with canonical JSON
+    # state and metadata.
     def replace(_id, messages:, state:, metadata:, actor_id: nil)
       raise AbstractMethodError, "#{self.class} must implement #replace"
     end