smith-agents 0.11.0 → 0.12.0

data/lib/smith/budget/request_hold.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "amount"
+
+module Smith
+  module Budget
+    # The hold a provider request asks a host's budget ledger for before it
+    # is sent: its output cap and an estimate of its input, priced from the
+    # pricing catalog.
+    #
+    # The output cap is the request's own (`max_tokens`, or its provider's
+    # name for it, as Providers::OutputLimit reads it), else the model's
+    # maximum, else for Anthropic DEFAULT_OUTPUT_CAP (what RubyLLM asks for
+    # when it knows no more), else the model's context window, else
+    # DEFAULT_OUTPUT_CAP; Smith.config.budget_hold_output_tokens, when set,
+    # caps it. The input estimate counts text (messages, tool definitions
+    # and calls, the output schema) at one token per BYTES_PER_TOKEN bytes,
+    # an image at IMAGE_TOKENS, a PDF at PAGE_TOKENS a page (its pages
+    # counted in it, else one per BYTES_PER_PAGE), another attachment's
+    # bytes as text, and each message's framing at MESSAGE_TOKENS, and is
+    # capped at the model's context window. Images and documents are
+    # recognized as RubyLLM attachments and in raw content blocks (base64
+    # `data` beside its media type, or a data URL). It is an estimate, not a
+    # bound: what the request spent replaces it.
+    module RequestHold
+      BYTES_PER_TOKEN = 3
+      IMAGE_TOKENS = 1_600
+      PAGE_TOKENS = 2_000
+      BYTES_PER_PAGE = 50_000
+      MESSAGE_TOKENS = 8
+      DEFAULT_OUTPUT_CAP = 4_096
+      OUTPUT_CAPS = Providers::OutputLimit::PARAM_PATHS.values.flatten(1).uniq.freeze
+
+      module_function
+
+      # The hold for a request RubyLLM's Provider#complete is about to make,
+      # from its `messages:`, `tools:`, `schema:` and `params:`.
+      def for_request(provider:, model:, mode: :sync, **request)
+        context_window = model.context_window if model.respond_to?(:context_window)
+        input = [input_estimate(*request.values_at(:messages, :tools, :schema)), context_window].compact.min
+        output = [output_cap(provider, request[:params], model), Smith.config.budget_hold_output_tokens].compact.min
+        Amount.new(input_tokens: input, output_tokens: output,
+                   cost: Pricing.compute_cost(model: model.id, provider: provider.to_s, input_tokens: input,
+                                              output_tokens: output, mode:))
+      end
+
+      def input_estimate(messages, tools, schema)
+        counter = Counter.new
+        Array(messages).each { counter.message(_1) }
+        tools.to_h.each_value { counter.tool(_1) }
+        counter.text(schema) if schema
+        counter.tokens
+      end
+
+      PAGE = %r{/Type\s*/Page(?![a-zA-Z])}n
+      PAGES = ObjectSpace::WeakMap.new
+      PAGES_LOCK = Mutex.new
+      private_constant :PAGE, :PAGES, :PAGES_LOCK
+
+      # A PDF's pages (its bytes from the block), counted in it once per
+      # String, else one per BYTES_PER_PAGE.
+      def pages(source)
+        PAGES_LOCK.synchronize do
+          PAGES[source] ||= begin
+            bytes = yield(source).b
+            counted = bytes.scan(PAGE).length
+            counted.positive? ? counted : [(bytes.bytesize + BYTES_PER_PAGE - 1) / BYTES_PER_PAGE, 1].max
+          end
+        end
+      end
+
+      def output_cap(provider, params, model)
+        paths = Providers::OutputLimit::PARAM_PATHS.fetch(provider.to_s, OUTPUT_CAPS)
+        [paths.lazy.filter_map { Providers::OutputLimit.lookup(params.to_h, _1) }.first,
+         (model.max_tokens if model.respond_to?(:max_tokens)),
+         (DEFAULT_OUTPUT_CAP if provider.to_s == "anthropic"),
+         (model.context_window if model.respond_to?(:context_window))]
+          .find { _1.is_a?(Integer) && _1.positive? } || DEFAULT_OUTPUT_CAP
+      end
+
+      # Counts what a request carries: bytes of text, images, document pages
+      # and messages.
+      class Counter
+        IMAGE_BLOCKS = %w[image input_image image_url].freeze
+        DOCUMENT_BLOCKS = %w[document file input_file].freeze
+        SOURCE_KEYS = %i[source inline_data inlineData].freeze
+        MEDIA_KEYS = %i[media_type mime_type mimeType].freeze
+        DATA_URL = %r{\Adata:([\w.+-]+/[\w.+-]+);base64,}
+
+        def initialize
+          @bytes = 0
+          @images = 0
+          @pages = 0
+          @messages = 0
+        end
+
+        def tokens
+          ((@bytes + BYTES_PER_TOKEN - 1) / BYTES_PER_TOKEN) + (@images * IMAGE_TOKENS) + (@pages * PAGE_TOKENS) +
+            (@messages * MESSAGE_TOKENS)
+        end
+
+        def message(message)
+          @messages += 1
+          content(message.content)
+          Array(message.tool_calls&.values).each { text(_1.to_h) } if message.respond_to?(:tool_calls)
+          thinking = message.thinking if message.respond_to?(:thinking)
+          text(thinking.text) if thinking.respond_to?(:text)
+        end
+
+        def tool(tool)
+          text(tool.name)
+          text(tool.description)
+          text(tool.params_schema) if tool.respond_to?(:params_schema)
+        end
+
+        def content(content)
+          case content
+          when RubyLLM::Content::Raw then raw(content.value)
+          when RubyLLM::Content
+            text(content.text)
+            content.attachments.each { attachment(_1) }
+          else raw(content)
+          end
+        end
+
+        def attachment(attachment)
+          return @images += 1 if attachment.image?
+          # A URL is not fetched to count it: one page.
+          return @pages += 1 if attachment.url?
+          return @pages += RequestHold.pages(attachment.content.to_s) { _1 } if attachment.pdf?
+
+          @bytes += attachment.content.to_s.bytesize
+        end
+
+        # Raw content: an image block, a block of base64 data or a data URL
+        # counts as what it carries; anything else as its text.
+        def raw(value)
+          case value
+          when Hash then block(value)
+          when Array then value.each { raw(_1) }
+          when String then string(value)
+          else text(value)
+          end
+        end
+
+        def block(hash)
+          kind = fetch(hash, :type).to_s
+          return @images += 1 if IMAGE_BLOCKS.include?(kind)
+
+          data, media = base64_data(hash)
+          return base64(data, media) if data
+          return @pages += 1 if DOCUMENT_BLOCKS.include?(kind) && !text_source?(hash)
+
+          hash.each do |key, value|
+            text(key)
+            raw(value)
+          end
+        end
+
+        # Anthropic's `source` (base64), Gemini's `inline_data`, or the
+        # block's own `data` beside a media type.
+        def base64_data(hash)
+          source = first(hash, SOURCE_KEYS) || hash
+          return unless source.is_a?(Hash) && fetch(source, :type) != "text"
+
+          data = fetch(source, :data)
+          media = first(source, MEDIA_KEYS)
+          [data, media] if data.is_a?(String) && media.is_a?(String)
+        end
+
+        def first(hash, keys) = keys.lazy.filter_map { fetch(hash, _1) }.first
+
+        def text_source?(hash)
+          source = fetch(hash, :source)
+          source.is_a?(Hash) && %w[text content].include?(fetch(source, :type).to_s)
+        end
+
+        def string(value)
+          url = DATA_URL.match(value)
+          url ? base64(value, url[1], from: url[0].bytesize) : text(value)
+        end
+
+        # Base64 data (from byte `from` of `encoded`): an image, a PDF's
+        # pages, or its decoded size as text. Only a PDF is decoded.
+        def base64(encoded, media, from: 0)
+          return @images += 1 if media.start_with?("image/")
+          if media == "application/pdf"
+            return @pages += RequestHold.pages(encoded) { _1.byteslice(from..).unpack1("m") }
+          end
+
+          @bytes += (encoded.bytesize - from) * 3 / 4
+        end
+
+        def fetch(hash, key) = hash.key?(key) ? hash[key] : hash[key.to_s]
+
+        def text(value)
+          case value
+          when nil then nil
+          when String then @bytes += value.bytesize
+          when Symbol then @bytes += value.to_s.bytesize
+          else @bytes += JSON.generate(value).bytesize
+          end
+        rescue JSON::GeneratorError, JSON::NestingError, Encoding::UndefinedConversionError
+          @bytes += value.to_s.bytesize
+        end
+      end
+    end
+  end
+end

data/lib/smith/budget/spent_reservation.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Smith
+  module Budget
+    # Reserving for spending that has already happened (a batch result
+    # delivered after its request was admitted): never refused, so the
+    # reservation can be reconciled with what was spent, past the limits if
+    # need be. Part of Ledger.
+    module SpentReservation
+      def reserve_spent!(reservations)
+        amounts = validated_amounts(reservations, "budget reservation")
+        @mutex.synchronize { create_reservation(amounts, checked: false) }
+      end
+    end
+  end
+end
+
+Smith::Budget::Ledger.include(Smith::Budget::SpentReservation)

data/lib/smith/child_run.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Smith
+  # One run a `map`, `call` or `spawn` step asks the host's run launcher to
+  # start: its `ref` (the index of its item, so the same on every replay of
+  # the step), its `key` (the step's token and the ref together: what the
+  # launcher must be idempotent on, unique across every child-run step of
+  # every run), its workflow class, the context `input:` returned for it,
+  # the untrusted keys it inherits from its parent (the parent's untrusted
+  # keys that `input:` passed under the same names), and the artifact
+  # namespaces it may read (its parent's and the parent's ancestors', the
+  # nearest first), so a document a parent stored reaches its children.
+  ChildRun = Data.define(:ref, :key, :workflow, :input, :untrusted_keys, :artifact_namespaces) do
+    def self.key_for(await_token, ref) = Digest::SHA256.hexdigest("smith.child_run.v1:#{await_token}:#{ref}")
+
+    def initialize(artifact_namespaces: [], **)
+      super
+    end
+
+    # The child, built with what it inherits in force; both persist with
+    # it, so a restored child keeps them.
+    def build
+      Workflow::StepIO.with_inherited_untrusted_keys(untrusted_keys) do
+        Workflow::ArtifactIntegration.with_inherited_artifact_namespaces(artifact_namespaces) do
+          workflow.new(context: input)
+        end
+      end
+    end
+
+    # The entry a host reports for a finished child when it resumes the
+    # parent: `{ ref:, status: "succeeded" | "failed", state:, output: }`.
+    # A child failed when it ended in its failed state or any of its steps
+    # raised, even one its own `on_failure` handled.
+    def self.result(ref:, run_result:)
+      failed = run_result.failed? || Array(run_result.steps).any? { _1.is_a?(Hash) && _1.key?(:error) }
+      { ref:, status: failed ? "failed" : "succeeded", state: run_result.state&.to_s, output: run_result.output }
+    end
+  end
+end

data/lib/smith/child_runs_failed.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "diagnostic_text"
+
+module Smith
+  # A `map` or `call` step whose child runs did not all succeed, under
+  # `on_item_failure: :fail`. Its failure family is `child_runs_failed`;
+  # details name the transition, up to MAX_REFS failed refs and the counts,
+  # and persist with the failed step.
+  class ChildRunsFailed < WorkflowError
+    DETAIL_NAMES = %i[transition failed_refs failed total].freeze
+    DETAIL_KEYS = DETAIL_NAMES.to_h { |name| [name.to_s.freeze, name] }.freeze
+    MAX_REFS = 20
+    private_constant :DETAIL_NAMES, :DETAIL_KEYS
+
+    attr_reader :transition, :failed_refs, :failed, :total
+
+    def initialize(transition:, failed_refs:, total:, failed: failed_refs.length, message: nil)
+      @transition = DiagnosticText.capture(transition.to_s, max_bytes: 256)
+      @failed_refs = Array(failed_refs).first(MAX_REFS).freeze
+      @failed = failed
+      @total = total
+      super(message || "#{failed} of #{total} child runs of #{@transition} failed (refs #{@failed_refs.join(", ")})")
+    end
+
+    def details = { transition:, failed_refs:, failed:, total: }.freeze
+
+    def self.from_details(details, message: nil)
+      raise ArgumentError, "child run failure details must be a Hash" unless details.is_a?(Hash)
+
+      values = details.to_h { |key, value| [key.is_a?(Symbol) ? key : DETAIL_KEYS[key], value] }
+      unless values.keys.sort == DETAIL_NAMES.sort && valid_counts?(values)
+        raise ArgumentError, "child run failure details are invalid"
+      end
+
+      new(transition: values[:transition], failed_refs: values[:failed_refs], failed: values[:failed],
+          total: values[:total], message:)
+    end
+
+    # Counts within bounds, and refs that are distinct indexes of the total,
+    # as many as the failures up to MAX_REFS (so neither count is negative).
+    def self.valid_counts?(values)
+      refs, failed, total = values.values_at(:failed_refs, :failed, :total)
+      return false unless values[:transition].is_a?(String) && [failed, total].all?(Integer)
+
+      failed <= total && valid_refs?(refs, failed, total)
+    end
+
+    def self.valid_refs?(refs, failed, total)
+      refs.is_a?(Array) && refs.all? { _1.is_a?(Integer) && _1.between?(0, total - 1) } &&
+        refs.length == [failed, MAX_REFS].min && refs.uniq.length == refs.length
+    end
+    private_class_method :valid_counts?, :valid_refs?
+  end
+end

data/lib/smith/content.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Smith
+  # Content parts of a Smith::Message: text, and documents and images held
+  # as artifacts of the run (`Smith.artifacts.store` inside a step), never
+  # as bytes, so a message with parts stays small and JSON-shaped wherever
+  # it is stored or digested.
+  #
+  #   ref = Smith.artifacts.store(pdf_bytes, content_type: "application/pdf")
+  #   Smith::Message.user([Smith::Content.document(ref, media_type: "application/pdf"),
+  #                        Smith::Content.text("List the parties to this contract.")])
+  #
+  # `cache: true` marks the part as the end of a prefix Anthropic may cache;
+  # other providers cache on their own and ignore it.
+  module Content
+    DOCUMENT_TYPES = %w[application/pdf text/plain].freeze
+    IMAGE_TYPES = %w[image/png image/jpeg image/gif image/webp].freeze
+    MAX_TEXT_BYTES = 1024 * 1024
+    MAX_REF_BYTES = 1024
+    # The bytes one document part may hold when it is sent: as base64 it
+    # still fits a 32 MiB request.
+    MAX_PART_BYTES = 24 * 1024 * 1024
+    # An artifact ref as Smith's stores make them: a run's namespace, then
+    # colon-separated names of letters, digits, `-` and `_`. No path, dot or
+    # NUL can reach a store through it.
+    REF = /\A[A-Za-z0-9_-]+(?::[A-Za-z0-9_-]+)+\z/
+
+    module_function
+
+    def text(text, cache: false) = part({ "type" => "text", "text" => text }, cache)
+
+    def document(ref, media_type:, cache: false)
+      part({ "type" => "document", "artifact" => ref, "media_type" => media_type }, cache)
+    end
+
+    def image(ref, media_type:, cache: false)
+      part({ "type" => "image", "artifact" => ref, "media_type" => media_type }, cache)
+    end
+
+    def part(fields, cache)
+      raise WorkflowError, "a content part's cache: must be true or false" unless [true, false].include?(cache)
+
+      check!(cache ? fields.merge("cache" => true) : fields)
+    end
+
+    # A part, String or Symbol keyed (and Symbol valued), checked and
+    # returned frozen with String keys and UTF-8 Strings: a text part with
+    # more than whitespace, or a document or image part naming an artifact
+    # (REF) and a media type of its kind, each with an optional
+    # `"cache" => true`.
+    def check!(value)
+      fields = value.is_a?(Hash) ? value.to_h { |key, field| [key.to_s, utf8(field)] } : {}
+      unless valid?(fields)
+        raise WorkflowError, "a content part is Smith::Content.text, .document or .image (documents " \
+                             "#{DOCUMENT_TYPES.join(", ")}; images #{IMAGE_TYPES.join(", ")})"
+      end
+
+      fields.freeze
+    end
+
+    def utf8(field)
+      return field.to_s.freeze if field.is_a?(Symbol)
+      return field unless field.is_a?(String)
+
+      field.dup.force_encoding(Encoding::UTF_8).freeze
+    end
+
+    def valid?(fields)
+      return false unless fields.fetch("cache", true) == true
+
+      keys = fields.keys - ["cache"]
+      case fields["type"]
+      when "text" then keys.sort == %w[text type] && text?(fields["text"])
+      when "document" then held?(keys, fields, DOCUMENT_TYPES)
+      when "image" then held?(keys, fields, IMAGE_TYPES)
+      else false
+      end
+    end
+
+    def text?(text) = bounded?(text, MAX_TEXT_BYTES) && text.match?(/\S/)
+
+    def held?(keys, fields, media_types)
+      keys.sort == %w[artifact media_type type] && bounded?(fields["artifact"], MAX_REF_BYTES) &&
+        REF.match?(fields["artifact"]) && media_types.include?(fields["media_type"])
+    end
+
+    def bounded?(value, max_bytes)
+      value.is_a?(String) && value.valid_encoding? && value.bytesize.between?(1, max_bytes)
+    end
+
+    def cached?(part) = part["cache"] == true
+    private_class_method :part, :utf8, :valid?, :text?, :held?, :bounded?
+  end
+end

data/lib/smith/context/session.rb

@@ -5,11 +5,12 @@ module Smith
     class Session
       attr_reader :messages
 
-      def initialize(messages:, context_manager:, persisted_context:, seed_message_count: 0)
+      def initialize(messages:, context_manager:, persisted_context:, seed_message_count: 0, untrusted_keys: nil)
         @messages = messages
         @context_manager = context_manager
         @persisted_context = persisted_context
         @seed_message_count = seed_message_count
+        @untrusted_keys = untrusted_keys
       end
 
       def inject_state!
@@ -19,10 +20,21 @@ module Smith
         return unless formatter
 
         @messages.replace(
-          StateInjection.inject(@messages, formatter: formatter, persisted: @persisted_context)
+          StateInjection.inject(@messages, formatter: formatter, persisted: trusted_context)
         )
       end
 
+      # The context without its untrusted keys: the run's own and those of
+      # any workflow it is nested in, when the run passes them, or else its
+      # context manager's.
+      def trusted_context
+        untrusted = @untrusted_keys
+        untrusted ||= @context_manager.respond_to?(:untrusted_keys) ? @context_manager.untrusted_keys : []
+        return @persisted_context if untrusted.empty? || !@persisted_context.is_a?(Hash)
+
+        @persisted_context.except(*untrusted)
+      end
+
       def masked_view
         return @messages unless @context_manager
 

data/lib/smith/context/state_injection.rb

@@ -9,10 +9,7 @@ module Smith
         text = formatter.call(persisted).to_s
         content = "#{MARKER}\n#{text}"
 
-        existing_index = messages.index do |message|
-          message_content = message[:content] || message["content"]
-          message_content.is_a?(String) && message_content.start_with?(MARKER)
-        end
+        existing_index = messages.index { |message| injected_state?(message) }
 
         if blank?(text)
           without_marker(messages, existing_index)
@@ -23,12 +20,20 @@ module Smith
         end
       end
 
+      # Only a system message carries the marker: hosts cannot admit system
+      # messages, so a user, assistant or tool message that starts with the
+      # marker is content, never Smith's injected state.
+      def self.injected_state?(message)
+        content = message[:content] || message["content"]
+        (message[:role] || message["role"]).to_s == "system" && content.is_a?(String) && content.start_with?(MARKER)
+      end
+
       def self.blank?(text) = text.valid_encoding? && text.strip.empty?
 
       def self.without_marker(messages, index)
         index ? messages.dup.tap { |msgs| msgs.delete_at(index) } : messages
       end
-      private_class_method :blank?, :without_marker
+      private_class_method :blank?, :without_marker, :injected_state?
     end
   end
 end

data/lib/smith/context.rb

@@ -10,6 +10,7 @@ module Smith
         subclass.instance_variable_set(:@persist_mode, @persist_mode || :explicit)
         subclass.instance_variable_set(:@persist_auto_seed, (@persist_auto_seed || []).dup)
         subclass.instance_variable_set(:@inject_state, @inject_state)
+        subclass.instance_variable_set(:@untrusted_keys, (@untrusted_keys || []).dup)
       end
 
       def session_strategy(strategy = nil, **opts)
@@ -23,6 +24,7 @@ module Smith
           return @persist_keys || []
         end
 
+        validate_persist_keys!(keys)
         if also && !keys.include?(:auto)
           raise Smith::WorkflowError, ":also is only valid alongside :auto"
         end
@@ -47,10 +49,36 @@ module Smith
         @persist_mode || :explicit
       end
 
+      def validate_persist_keys!(keys)
+        invalid = keys.grep_v(Symbol)
+        return if invalid.empty?
+
+        raise Smith::WorkflowError, "persist keys must be Symbols, got #{invalid.map(&:inspect).join(", ")}"
+      end
+      private :validate_persist_keys!
+
       def persist_auto_seed
         @persist_auto_seed || []
       end
 
+      # Keys whose values come from outside the system (a fetched document,
+      # an inbound message), or that a step derived from such a value:
+      # `inject_state` formatters and the `seed_messages` builder never
+      # receive them, and an agent that names one in `inputs` is refused,
+      # in this workflow and in any workflow it nests.
+      def untrusted(*keys)
+        return untrusted_keys if keys.empty?
+
+        validate_persist_keys!(keys)
+        raise Smith::WorkflowError, "untrusted takes context keys, not :auto" if keys.include?(:auto)
+
+        @untrusted_keys = (untrusted_keys + keys).uniq
+      end
+
+      def untrusted_keys
+        @untrusted_keys || []
+      end
+
       def inject_state(&block)
         return @inject_state unless block_given?
 

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

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+
+module Smith
+  module Doctor
+    module Checks
+      # The artifact store: configured, buildable, usable, and as durable as
+      # the workflow state, since a run that waits, retries or resumes in
+      # another process reads its artifacts there.
+      module Artifacts
+        PROCESS_LOCAL = %w[Smith::Artifacts::Memory].freeze
+        COLUMNS = %w[ref data content_type execution_namespace created_at].freeze
+
+        def self.run(report)
+          raw = ::Smith.config.artifact_store
+          return report.add(**missing) if raw.nil? && !::Smith.config.test_mode
+
+          store = ::Smith.artifact_backend
+          report.add(name: "artifacts.store", status: :pass, message: "Artifact store: #{store_name(store)}")
+          check_usable(report, store)
+          check_durability(report, store)
+          check_ownership(report, store)
+        rescue StandardError => e
+          report.add(name: "artifacts.store", status: :fail, message: "Artifact store configuration is invalid",
+                     detail: e.message)
+        end
+
+        def self.store_name(store) = store.is_a?(Module) ? store.name : store.class.name
+
+        def self.missing
+          { name: "artifacts.store", status: :warn, message: "No artifact store configured",
+            detail: "Set config.artifact_store to :s3 (S3, R2), :active_record, :file, or a store, with " \
+                    "config.artifact_options; steps that store artifacts or read documents fail without one" }
+        end
+
+        # The table an Active Record store writes, the directory a File
+        # store writes, the bucket an S3 store writes.
+        def self.check_usable(report, store)
+          problem = case store
+                    when ::Smith::Artifacts::ActiveRecordStore then table_problem(store)
+                    when ::Smith::Artifacts::File then directory_problem(store)
+                    when ::Smith::Artifacts::S3 then bucket_problem(store)
+                    end
+          return unless problem
+
+          report.add(name: "artifacts.usable", status: :warn, message: "The artifact store cannot be used",
+                     detail: problem)
+        end
+
+        def self.table_problem(store)
+          missing = COLUMNS - store.model.column_names
+          "#{store.model.name} lacks the columns #{missing.join(", ")}" if missing.any?
+        rescue StandardError => e
+          "the store's model cannot be loaded: #{e.message}"
+        end
+
+        def self.directory_problem(store)
+          dir = store.instance_variable_get(:@dir)
+          "the directory #{dir} is not writable" unless ::File.directory?(dir) && ::File.writable?(dir)
+        end
+
+        def self.bucket_problem(store)
+          client = store.instance_variable_get(:@client)
+          return unless client.respond_to?(:head_bucket)
+
+          client.head_bucket(bucket: store.instance_variable_get(:@bucket))
+          nil
+        rescue StandardError => e
+          "the bucket cannot be reached: #{e.class.name}"
+        end
+
+        def self.check_durability(report, store)
+          adapter = ::Smith.config.persistence_adapter
+          return unless PROCESS_LOCAL.include?(store.class.name) && adapter && !process_local_state?(adapter)
+
+          report.add(
+            name: "artifacts.durability", status: :warn,
+            message: "Artifacts are kept in process memory while workflow state is persisted",
+            detail: "A run that waits, retries or resumes in another process loses its artifacts; configure :s3, " \
+                    ":active_record or :file"
+          )
+        end
+
+        def self.process_local_state?(adapter)
+          adapter.to_s == "memory" || adapter.is_a?(::Smith::PersistenceAdapters::Memory)
+        end
+
+        def self.check_ownership(report, store)
+          return if store.respond_to?(:stored_by?)
+
+          report.add(
+            name: "artifacts.ownership", status: :warn,
+            message: "The artifact store cannot tell which run stored a ref (stored_by?)",
+            detail: "Runs read any ref under their prefix, and content parts cannot read documents from it"
+          )
+        end
+        private_class_method :store_name, :missing, :check_usable, :table_problem, :directory_problem, :bucket_problem,
+                             :check_durability, :process_local_state?, :check_ownership
+      end
+    end
+  end
+end

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

@@ -6,7 +6,6 @@ module Smith
       module Configuration
         def self.run(report)
           check_logger(report)
-          check_artifact_store(report)
           check_trace_adapter(report)
           check_pricing(report)
         end
@@ -21,16 +20,6 @@ module Smith
           )
         end
 
-        def self.check_artifact_store(report)
-          configured = !::Smith.config.artifact_store.nil?
-          report.add(
-            name: "config.artifact_store",
-            status: configured ? :pass : :warn,
-            message: configured ? "Artifact store configured" : "No artifact store configured",
-            detail: configured ? nil : "Large outputs will use in-memory default"
-          )
-        end
-
         def self.check_trace_adapter(report)
           configured = !::Smith.config.trace_adapter.nil?
           report.add(