smith-agents 0.12.0 → 0.12.2

data/docs/AGENTS.md

@@ -0,0 +1,238 @@
+# Agents
+
+How an agent's replies are checked, how its requests are shaped for each
+provider, and the two other ways a step can call it: streamed, and in batch.
+
+## Registering agents
+
+Agents register at class load. In Rails, register workflow-facing agents in a `to_prepare` hook so autoload doesn't drop them:
+
+```ruby
+# config/initializers/smith_agents.rb
+Rails.application.config.to_prepare do
+  ReplyAgent
+  TriageAgent
+end
+```
+
+## Agent outputs
+
+Smith reads how each response ended from the provider's stop reason. A
+response cut off at its output limit, a refused one, and a structured output
+that is not what the agent declares are not accepted as the step's output:
+
+```ruby
+class Reviewer < Smith::Agent
+  model "claude-opus-5-5", provider: :anthropic
+  output_schema ReviewSchema                         # its root is an object
+  output_contract ReviewContract                     # call(hash) => true, false, or a result with success? and errors
+  output_repairs 1                                   # the default; 0 turns repair off
+  on_truncation retry_with: { max_tokens: 64_000 }   # or :fail (the default), or :accept
+  on_refusal fallback: "openai/gpt-5"                # or :fail (the default)
+end
+```
+
+- A cut-off response raises `Smith::OutputTruncated`, unless the agent
+  accepts it or retries it once on the same model with a larger output limit,
+  mapped to the provider's own parameter (Anthropic, OpenAI, Gemini, Vertex AI
+  and Bedrock; another provider is not retried). There is no retry when the
+  response ran out of context rather than output, or when the new limit is no
+  larger than the request had (the agent's own parameter, or for Anthropic the
+  model's maximum, which RubyLLM already sends); a later repair keeps the
+  larger limit.
+- A refused response (a Gemini prompt block included) raises
+  `Smith::OutputRefused`, unless the agent falls back once to another model.
+- Every other response then goes through the agent's `after_completion`. A
+  structured output (an `output_schema`, or a static RubyLLM `schema`) that is
+  not a JSON object, breaks a schema constraint, or fails the output contract
+  goes back to the same model up to `output_repairs` times: the step's messages
+  as the provider got them, the rejected reply as the assistant's, and the
+  problems as "path: problem" lines. It then raises `Smith::OutputInvalid`,
+  whose `problems` lists at most 20 of them. A blank output still raises
+  `Smith::BlankAgentOutputError`.
+- No follow-up call is made once a tool has run in the step (the tools would
+  run again; the step fails with `Smith::ToolOutcomeUncertain` around the output
+  error) or once the call has spent what its step reserved from a budget. A
+  follow-up that fails raises the output error it was making up for, with the
+  provider's error as its cause.
+- Anthropic's structured outputs reject numeric, string-length and most
+  array-size constraints: Smith sends Anthropic the schema without them, with
+  `additionalProperties: false` on every object, and checks them on the parsed
+  output for every provider. An object that allows other properties or
+  declares none cannot be sent to Anthropic; the step fails before the call
+  with a `Smith::WorkflowError`, and runtime readiness reports
+  `:output_schema_unsupported` for an agent declared for Anthropic.
+- An agent with no model and no fallback models fails its step with a
+  `Smith::WorkflowError`; runtime readiness reports it (`:agent_without_model`).
+
+Every response is billed and settles into budgets, whatever happens to its
+output, and each rejected one leaves an `:output_rejected` trace naming its
+attempt. The output errors share the failure family `output_failure`, persist
+with a failed step, and are never retried by `Smith::Errors.retryable?`, a job
+retry on `Smith::Errors.retryable_classes`, or a transition's
+`retry_on Smith::AgentError`: Smith's own retry, fallback and repairs have run.
+
+## Models and request shaping
+
+Smith ships a per-attempt normalizer that translates the request payload to whatever the resolved model's provider family expects:
+
+- Anthropic Opus 4.7+ adaptive thinking via `output_config[:effort]`
+- Anthropic 4.0–4.6 budget_tokens
+- OpenAI gpt-5 family reasoning_effort with `/v1/responses` routing when tools + thinking are combined
+- Gemini 2.5+ budget_tokens
+
+Override the inferred profile per-app via `Smith::Models.register(Profile.new(...))`.
+Profiles are keyed by both provider and model id. Pass `provider:` to
+`Smith::Models.find` or `find_or_infer` whenever an id exists under more than
+one provider; an ambiguous unqualified lookup fails closed. Smith never
+hardcodes model ids in the library.
+
+Provider-qualified fallback entries use the same exact identity:
+
+```ruby
+fallback_models(
+  { model: "claude-sonnet-4-6", provider: :anthropic },
+  { model: "openai/gpt-5", provider: :openrouter }
+)
+```
+
+Fallback entries must include an explicit provider. Smith does not infer a
+fallback provider from the primary model or from a model id because the same id
+may be registered by more than one provider. Unqualified fallback entries fail
+closed during agent configuration.
+
+## Streaming
+
+An agent step can send its reply's text to the host as the model writes it:
+
+```ruby
+# Called when a streamed step starts; returns the step's sink, or nil to
+# stream nothing (nobody is watching). Each step execution gets its own.
+Smith.config.stream_sinks = {
+  answer: ->(info) { AnswerStream.new(info[:execution_key]) if Screens.watching?(info[:execution_key]) }
+}
+
+class AnswerStream
+  def initialize(key)
+    @key = key
+    @reply = Smith::Streaming::JsonField.new(:reply)  # the output schema's reply field, as it grows
+  end
+
+  def delta(text) = (piece = @reply.push(text)) && Screens.append(@key, piece)
+  def reset(_reason) = @reply.reset || Screens.clear(@key)
+  def finish(output) = Screens.final(@key, output["reply"])
+  def fail(_error_class) = Screens.failed(@key)
+end
+
+class Answer < Smith::Workflow
+  initial_state :asked
+  state :failed
+
+  transition :answer, from: :asked, to: :answered do
+    execute :answerer, stream: :answer, output_to: :answer
+    on_failure :fail
+  end
+end
+```
+
+A sink defines any of `start(info)` (each provider call: the step's info with
+the attempt, model and provider), `delta(text)` (each text chunk; tool calls,
+thinking and `<think>` text are not sent), `reset(reason)` (Smith discarded the
+text sent so far: `:retry`, `:fallback`, `:truncation` or `:repair`; and
+`:retry_wait`, the last word, while a durable retry waits), `finish(output)`
+(the output the step accepted, after guardrails, the output contract and
+`output_to:`, once the step is stored) and `fail(error_class)`. Streamed text is
+a draft: guardrails and output checks run on the whole reply, so nothing should
+be saved or acted on before `finish`, and a step with an output schema streams
+JSON text (`Smith::Streaming::JsonField` gives the text each delta adds to one
+string field). A sink that raises is logged and the step goes on; a sink name
+that is not registered fails the step before its call. Stop reasons are read
+from the stream, so cut-off and refused replies are handled as without it, and a
+stream that ends without one counts as cut off (`stream_incomplete`). Smith's
+OpenAI Responses path does not stream: its sink gets each reply as one delta.
+Streaming changes nothing durable (each usage entry keeps its response's stop
+reason and message id, with `mode: :stream`), and a replayed step streams again
+(unless a response memo kept its reply: then its sink gets the text at once).
+Graph inspection shows the stream, and runtime readiness reports a missing sink
+(`:stream_sink_missing`) and an agent whose calls go to the Responses API
+(`:stream_whole_replies`).
+
+## Batch mode
+
+An agent step, or a fan-out, can send its requests through a provider's batch
+API (half price, answered within 24 hours) instead of over the wire:
+
+```ruby
+# The host keeps each request until a scheduled job submits it (a table, in
+# production); enqueue is idempotent on custom_id.
+class HostBatchQueue
+  Entry = Struct.new(:custom_id, :await_token, :request, :run_key, :batch_id)
+
+  def initialize = @entries = {}
+  def enqueue(custom_id:, await_token:, request:, execution_key:)
+    @entries[custom_id] ||= Entry.new(custom_id, await_token, request, execution_key)
+  end
+  def unsubmitted = @entries.values.reject(&:batch_id)
+  def entry(custom_id) = @entries.fetch(custom_id)
+end
+Smith.config.batch_queue = HostBatchQueue.new
+
+class Triage < Smith::Workflow
+  initial_state :queued
+  state :failed
+
+  transition :triage, from: :queued, to: :triaged do
+    execute :triager, mode: ->(ctx) { ctx[:urgent] ? :sync : :batch }, output_to: :verdict
+    on_failure :fail
+  end
+end
+
+# One scheduled job submits what is queued; another collects an ended batch
+# and resumes each run once with every result of its wait.
+queue = Smith.config.batch_queue
+batches = Smith::Providers::Anthropic::Batches.new
+entries = queue.unsubmitted
+batch_id = batches.submit(entries.map { { custom_id: _1.custom_id, request: _1.request } })
+entries.each { _1.batch_id = batch_id }
+if batches.status(batch_id)[:status] == "ended"
+  payloads = Hash.new { |hash, wait| hash[wait] = {} }
+  batches.results(batch_id) do |custom_id, result|
+    entry = queue.entry(custom_id)
+    payloads[[entry.run_key, entry.await_token]][custom_id] = result
+  end
+  payloads.each { |(run_key, token), payload| Triage.resume!(run_key, event: :batch_result, token:, payload:) }
+end
+```
+
+`mode:` is `:sync` (the default), `:batch`, or a callable of the context and
+the step attempt returning one, on `execute` and `fan_out`; a batch step
+declares `on_failure`, and cannot stream or be `parallel:`. Smith prepares
+the call as a synchronous one, admits it against the budget, and hands the
+exact request (the provider payload and the call's own headers, never the
+connection's credentials) to the queue under a `custom_id` (the wait's token;
+each fan-out branch its own) once the step's attempt has ended without error,
+then the run waits on `:batch_result`. Smith never submits or polls, and waits
+without sleeping: `Smith::Providers::Anthropic::Batches` gives the host
+`submit`, `status`, `results` and `cancel`. `resume!` with
+`{custom_id => result}` runs the step again, each call taking its result as
+the reply it would have got. A call that renders another request by then (a
+date in its prompt, data read afresh, a prompt changed in a deploy) does what
+its step's `on_request_change:` says: `:keep` (the default) takes the result,
+which answers the request as sent, and its `:provider_call` trace says
+`request_changed: true`; `:resend` sends the request as rendered now over the
+wire instead; `:fail` fails the step with `Smith::BatchRequestChanged` (an
+`AgentError`, so `retry_on` can send it again, synchronously if the mode
+callable says so). A result the call does not use is charged all the same.
+Then the output checks, a follow-up call (over the
+wire), guardrails and `output_to:` as ever, usage recorded with `mode: :batch`
+and priced with the catalog's `batch_discount`, and charged even past a
+budget, as the money is spent. A request the provider refused fails the step
+(`Smith::BatchRequestInvalid`); a failed, canceled or expired result, or none
+by the wait's deadline (`expire_wait!`, 25 hours), raises
+`Smith::BatchResultFailed`, which `retry_on` sends again (synchronously, if the
+mode callable says so at the next attempt; an in-process `retry_on` backoff
+sleeps as on any step, while `durable: true` waits). Only Anthropic's batch interface is
+built in, and a batch request is one turn, so a batching agent has no tools;
+runtime readiness reports a missing queue (`:batch_queue_missing`) and an
+agent that cannot batch (`:batch_unavailable`), and graph inspection shows the
+mode.

data/docs/BUDGETS.md

@@ -0,0 +1,134 @@
+# Budgets and Deadlines
+
+```ruby
+class BudgetedWorkflow < Smith::Workflow
+  budget total_tokens: 10_000, total_cost: 0.50, wall_clock: 30
+end
+```
+
+`wall_clock` is in seconds. A workflow's `wall_clock` bounds the time its steps
+spend running, counted across restores in the persisted `active_seconds`, not
+the time since the run was created: time spent waiting, or between steps a host
+advances from a queue, does not count. A step that raised or whose process died
+(or met an interrupting error) is charged, on the next restore, the time from its start, at most what is left
+of the budget, so a run that keeps failing stays bounded across retries.
+Durable composite branches each start from what is left; their running time is
+not added back. An agent's `wall_clock` bounds each of
+its calls. A workflow budget accepts `total_tokens`,
+`token_limit`, `total_cost`, `tool_calls`, and `wall_clock`; an agent budget
+accepts `token_limit`, `cost`, `wall_clock`, `tool_calls`, `total_tokens`, and
+`total_cost`. Any other key raises `ArgumentError` naming the accepted keys. A
+restored run drops consumed amounts for keys the workflow no longer declares.
+
+Budgets reserve serially at each step and reconcile after the agent call. Parallel branches reserve scoped envelopes that release back to the parent ledger. The `Workflow::RunResult` carries `total_tokens`, `total_cost`, and per-call `usage_entries`. Token budgets and totals count prompt-cache reads and writes beside uncached input and output, and settle every billed response, including the completed rounds of a tool loop whose attempt then failed.
+
+Direct ledger integrations settle the exact receipt returned by reservation:
+
+```ruby
+reservation = ledger.reserve_many!(total_tokens: 1_000, total_cost: 0.10)
+ledger.reconcile_many!(reservation, actual: { total_tokens: 640, total_cost: 0.06 })
+```
+
+`release!` / `release_many!` accept the same receipt when work never starts.
+Receipts are ledger-owned and one-shot: another ledger, a replay, or an
+amount-only settlement is rejected. `ledger.remaining(key)` never reads back
+above the exact remaining amount, and `ledger.remaining_share(key, parts)`
+returns one of `parts` equal shares of it such that reserving all `parts` fits.
+
+Budget amounts accept finite, non-negative `Integer` and `Float` values. Smith
+uses an exact `BigDecimal` representation derived from each value's canonical
+decimal text and converts ledger snapshots back to ordinary JSON-safe numerics,
+avoiding cumulative binary Float drift without changing persisted workflow
+state shapes. Ledger arithmetic temporarily uses unlimited decimal precision and
+restores the host's existing `BigDecimal` precision limit before returning.
+
+Budget operations are atomic for normal concurrent callers and synchronous
+exceptions. Smith uses cooperative cancellation and never terminates branch
+threads with `Thread#raise` or `Thread#kill`. Arbitrary asynchronous thread
+termination can make any in-process return value outcome-ambiguous; hosts must
+use cancellation signals, bounded I/O, and process isolation for hard stops.
+
+## Budget ledgers
+
+A run's `budget` bounds that run. A budget shared by many runs (an account's
+monthly spend, say) lives in the host, and a workflow names it with
+`budget_ledger`:
+
+```ruby
+class MonthlyLedger
+  def initialize(account) = @account = account
+
+  # Admit the hold (true; anything else refuses it) and keep it under key
+  # until expires_at, after which it counts for nothing.
+  def reserve!(amount, key:, expires_at:) = ...
+  def reconcile!(key, amount) = ...   # what the request spent, in place of its hold
+  def release!(key) = ...             # it spent nothing
+end
+
+class DocumentReview < Smith::Workflow
+  budget_ledger(:account_id) { |scope| MonthlyLedger.new(scope[:account_id]) }
+end
+```
+
+The block gets the run's scope: the values the named keys have in its trusted
+context when the run is created (JSON scalars, kept with the run), so nothing a
+step or a model writes later chooses another ledger, and an untrusted key is
+refused. Smith builds the ledger at the first request a step makes, never
+persists it, and never needs it to restore a run; nil means none. A nested
+workflow without a `budget_ledger` of its own charges the enclosing run's; a
+child run (`call`, `map`, `spawn`), inline or not, uses its own class's, so
+give each child workflow its own (runtime readiness warns of one that has none,
+`:child_run_unbudgeted`) and pass its scope keys in each child's input.
+
+Before a call's first request over the wire (each fallback model, each
+follow-up, streamed or not, OpenAI's Responses route included) Smith asks the
+ledger to admit its hold. If the ledger refuses, the step fails with
+`Smith::BudgetUnavailable` (a `BudgetExceeded`, not retried by default) before
+anything is sent; `retry_on Smith::BudgetUnavailable, durable: true, ...` waits
+for budget instead (the host ends the wait with `expire_wait!`, and ends it
+early, once there is budget, with a `now:` at its `deadline_at`). After the request, Smith reconciles what it
+spent: its usage, or its hold when it answered without usage or its stream
+failed part way; a request that failed before anything came back releases its
+hold. If building the ledger or `reserve!` raises, the step fails with
+`Smith::BudgetLedgerError` (nothing was sent, no fallback model is tried); one
+from `reconcile!` or `release!` is logged by class and the step goes on, as
+the money is spent.
+
+A tool loop's later rounds continue a call whose tools already ran, so
+stopping one would leave the tools' effects without their answer. A step whose
+`retry_on` names `BudgetUnavailable` holds them too: when the ledger refuses
+one, the loop pauses, keeping its tool calls and their results (at most 1 MiB)
+with the step's retry, and the retry continues the loop from them, running
+none of its tools again. Any other step's later rounds, or a loop too large to
+keep, go on unheld and are reconciled with what they spent, so give tool-using
+agents a `tool_calls` budget.
+
+A hold (`Smith::Budget::Amount`: `input_tokens`, `output_tokens`, `cost`, and
+`tokens`, their sum) is the request's output cap (its `max_tokens`, or its
+provider's name for it, else the model's) and an estimate of its input: text
+at one token per 3 bytes, an image at 1,600 tokens, a PDF at 2,000 tokens a
+page, 8 tokens a message for its framing, capped at the model's context window.
+Images and documents count so as RubyLLM attachments and in raw content blocks
+(base64 data or a data URL). `Smith.config.budget_hold_output_tokens`, when
+set, caps the output part (an agent with no `max_tokens` is otherwise held for
+the model's maximum, which can be tens of thousands of tokens, and a longer
+reply is reconciled at what it cost). It is priced from the pricing catalog
+under the id RubyLLM resolves the model to; `cost` is nil for an unpriced
+model, which runtime readiness warns of (`:budget_ledger_unpriced`, for every
+agent that charges the ledger), and its readiness metrics name the scope keys.
+
+A key is the provider attempt's `attempt_id` (as on its `:provider_call` trace)
+and the request's round, `"<attempt_id>:<n>"`, and for a batch request its
+`custom_id`. A batch request is held when its step captures it, at the batch
+discount, and settled when its result comes: a succeeded result, used or not,
+is reconciled at what it cost; one that failed, or never came, is released.
+A process that dies during a request never settles its hold, so every hold
+carries `expires_at`: `Smith.config.budget_hold_ttl` from now (an hour by
+default; it must outlast the longest request), and for a batch request its
+25-hour wait longer. Smith runs no timer; the ledger leaves holds past
+`expires_at` out of what it admits, and still records a reconcile that comes
+later (a batch delivered late). A key may come again after a crash (a batch
+request captured again, a delivery that ran twice): a reserve of it replaces
+its hold, a release ends it, and its reconcile is final, recorded once.
+Fan-out branches call the ledger from their own threads. RubyLLM's own retries
+(`max_retries`) resend a request under its one hold.

data/docs/CONFIGURATION.md

@@ -30,7 +30,7 @@ Use agent classes for invocation behavior:
 - `fallback_models`
 - `register_as`
 
-The output macros are described in the README, Agent outputs.
+The output macros are described in [AGENTS.md](AGENTS.md), Agent outputs.
 
 ### 3. Workflow configuration: `Smith::Workflow`
 
@@ -115,8 +115,33 @@ Smith.configure do |config|
   # Batch steps (`execute Agent, mode: :batch`): the host's queue of requests.
   config.batch_queue = HostBatchQueue.new
 
-  # How long a request's hold on a workflow's budget_ledger lasts unsettled.
+  # How long a request's hold on a workflow's budget_ledger lasts unsettled,
+  # and the most output tokens a hold counts (nil: the request's own cap).
   config.budget_hold_ttl = 3600
+  config.budget_hold_output_tokens = nil
+
+  # Persistence: where runs are stored, and a stored state's bound.
+  config.persistence_adapter = :active_record
+  config.persistence_options = { model: "WorkflowState" }
+  config.persistence_ttl = nil              # :active_record cannot expire state
+  config.persistence_max_bytes = 16_777_216 # nil: no bound
+  config.persistence_retry_policy = { attempts: 3, base_delay: 0.1, max_delay: 1.0 }
+
+  # Child runs (`call`, `map`, `spawn`) and replays.
+  config.run_launcher = HostLauncher.new
+  config.response_memo = HostResponseMemo.new
+
+  # Errors that stop a step as if its worker had stopped, instead of failing it.
+  config.interrupting_errors = [ActiveRecord::ConnectionNotEstablished, ActiveRecord::ConnectionFailed]
+
+  # Generic runtime resource bounds.
+  config.parallel_branch_limit = 1_000
+  config.parallel_concurrency = 8
+  config.parallel_nesting_limit = 64
+  config.retry_attempt_limit = 100
+
+  # OpenAI /v1/responses routing for gpt-5 + tools + thinking: :auto (default) or :off.
+  config.openai_api_mode = :auto
 
   config.logger = Logger.new($stdout)
 end
@@ -169,14 +194,15 @@ from JSON or YAML has.
 | `pricing` | Best-known model-call cost catalog | Add once you care about `total_cost` |
 | `logger` | Smith's runtime logger | Usually the first setting to add |
 | `batch_queue` | Takes the requests `mode: :batch` steps send: `enqueue(custom_id:, await_token:, request:, execution_key:)`, idempotent on `custom_id`; the host submits them (`Smith::Providers::Anthropic::Batches`) and resumes each run with its results | Set before any workflow batches; readiness reports a missing one |
-| `response_memo` | Keeps what a step's provider calls got (`fetch(key)`, `store(key, record)`), so a step replayed after its process died reuses it instead of paying again (README, "Response memo") | Set it where replays happen: lax idempotency mode, or a host that runs a crashed step again |
+| `response_memo` | Keeps what a step's provider calls got (`fetch(key)`, `store(key, record)`), so a step replayed after its process died reuses it instead of paying again ([ERRORS_AND_RETRIES.md](ERRORS_AND_RETRIES.md), Response memo) | Set it where replays happen: lax idempotency mode, or a host that runs a crashed step again |
+| `interrupting_errors` | Subclasses of StandardError that interrupt a step instead of failing it, such as the host's database or queue out of reach: met in a step (or as the cause of an error that was, never through a provider's own failure), they take no route, no retry and no failure record, reach the caller as raised, and leave the run as the step left it. Smith does not count them ([ERRORS_AND_RETRIES.md](ERRORS_AND_RETRIES.md), Interrupting errors). None by default | Name the errors that mean your own systems failed, never ones a step can cause every time (a query timeout) |
 | `budget_hold_ttl` | Seconds a provider request's hold on a workflow's `budget_ledger` lasts unsettled (default 3600): each hold's `expires_at` is this from now, and a batch request's is its 25-hour wait longer. Past it the request's process is taken to have died | Raise it above the longest request (its retries and stream included) |
 | `budget_hold_output_tokens` | The most output tokens a request's hold on a workflow's `budget_ledger` counts (default nil: the request's own `max_tokens`, else the model's maximum). Only the hold changes, not the request; a longer reply is reconciled at what it cost | Set it when agents leave `max_tokens` unset and a small budget would refuse calls on their huge holds |
 | `stream_sinks` | The sinks `execute Agent, stream: :name` steps send text to, by name: callables that take a step's info (`stream`, `execution_key`, `transition`) and return that step's sink, or nil to stream nothing | Register each name a workflow streams to; readiness reports a missing one |
 | `persistence_adapter` | Adapter for durable workflow state | `:redis`, `:rails_cache`, `:active_record`, `:memory`, or a custom object |
 | `persistence_options` | Per-adapter options (client, namespace, model, columns) | See "Built-In Persistence Adapters" |
 | `persistence_ttl` | Global TTL for persisted state (Integer/Float seconds; nil = no expiry). `:active_record` cannot expire state, so its writes refuse a non-nil TTL (reads and deletes still work, and `smith doctor --durability` flags the combination) | Set when long-tail abandoned workflows accumulate in storage |
-| `persistence_max_bytes` | The most bytes a stored workflow state may take (nil, the default: no bound). A stored run's step whose result would take it past the bound fails with `Smith::PersistedStateTooLarge` (its `key`, `bytes` and `limit`) before the result is kept, as with any error: its usage is recorded and its `on_failure` taken, so the run stays storable, strict mode included. A tool loop refused for budget does not pause into a state past it (it goes on unheld). Any other state past it is refused before anything is written. The answer that did not fit is not kept. `rails g smith:install` sets it to 1 MiB, with a CHECK a third above it on the payload column | Set it above the largest output a step keeps, with a database CHECK on the payload, so an oversized state fails as a typed step error instead of a database one |
+| `persistence_max_bytes` | The most bytes a stored workflow state may take (nil, the default: no bound). A stored run's step whose result would take it past the bound fails with `Smith::PersistedStateTooLarge` (its `key`, `bytes` and `limit`) before the result is kept, as with any error: its usage is recorded and its `on_failure` taken, so the run stays storable, strict mode included. A tool loop refused for budget does not pause into a state past it (it goes on unheld). Any other state past it is refused before anything is written. The answer that did not fit is not kept. `rails g smith:install` sets it to 16 MiB (well above what one step can add: a map's collected results are at most 4 MiB, a wait's payload and a paused tool loop 1 MiB each), with a CHECK a third above it on the payload column | Set it above the largest output a step keeps, with a database CHECK on the payload, so an oversized state fails as a typed step error instead of a database one |
 | `persistence_retry_policy` | Exponential-backoff policy for transient adapter I/O failures | Defaults to `{ attempts: 3, base_delay: 0.1, max_delay: 1.0 }` |
 | `retry_attempt_limit` | Maximum attempts accepted by workflow and persistence retry policies | Defaults to `100` |
 | `parallel_branch_limit` | Maximum branches accepted by one homogeneous or heterogeneous fan-out | Defaults to `1_000` |

data/docs/DEVELOPMENT.md

@@ -0,0 +1,63 @@
+# Developing Smith
+
+## Verification discipline
+
+Tests are required, but they are never enough for runtime primitive changes.
+Every Smith workflow slice must also run practical gem-level execution probes.
+When a host application consumes unreleased Smith changes, point that host app at
+the local Smith repository and exercise the changed workflow paths in the host
+environment before calling the slice complete.
+
+## Algorithms
+
+Smith changes must not use brute-force graph search, validation, scheduling, or
+class-generation algorithms. Document the relevant time and space complexity,
+prefer indexed, linear, logarithmic, or otherwise bounded approaches, and treat
+an avoidable asymptotic regression as a release blocker.
+
+## Runtime complexity
+
+- Executable graph reachability is iterative `O(V + E)` time and `O(V)` space,
+  using indexed outgoing transitions and runtime-equivalent successor rules.
+- Smith-managed tool arguments are copied iteratively in `O(N + B)` time and
+  `O(N + B)` bounded space for `N` expanded JSON value occurrences and `B`
+  expanded encoded bytes. Reused subgraphs are charged for every serialized
+  occurrence, native `Array` and `Hash` operations bypass hostile overrides, and
+  every mutable container's native size is admitted before one shallow copy is
+  made. Smith verifies the copy retained the admitted size before allocating or
+  traversing children. One immutable dispatch collection remains authoritative
+  from host admission through RubyLLM execution. The complete provider batch is
+  bounded to 100 calls and 1 MiB of normalized UTF-8 call metadata. The capture
+  boundary transfers temporary ownership of the provider collection and argument
+  graph to Smith: callers must not mutate them concurrently. Smith detects changed
+  cardinality and fails closed, but Ruby cannot prevent an unrelated writer from
+  growing a caller-owned container between native size admission and the native
+  copy without freezing that caller-owned object.
+- Admitted tool-receipt settlement scans each batch once in `O(B)` time and
+  `O(B)` state for `B` admitted Smith calls, including when an earlier terminal
+  callback fails.
+- Parallel execution is `O(B)` scheduling and result space for `B` branches,
+  with at most `C = parallel_concurrency` active worker threads per top-level
+  execution. Re-entrant fan-out inherits the same cancellation signal and uses
+  only idle workers from the top-level execution context, falling back to the
+  current worker when no capacity remains. Nested calls fail closed before the
+  configurable nesting bound can exhaust Ruby's stack. Cancellation prevents
+  queued branch bodies from starting;
+  already-running branches are drained before control returns so work is never
+  detached. Branch adapters must use bounded I/O and honor the cancellation
+  signal. Hosts continue to own process-level concurrency and hard deadlines.
+- Reservation and settlement across `L` declared budget dimensions and `D`
+  operation dimensions is `O(L + D)` time and space. Receipt lookup is expected
+  `O(1)`; no operation scans or copies the active receipt registry. Integer and
+  Float amounts use exact decimal arithmetic internally.
+- Retry delay calculation is `O(1)` time and space per attempt. A policy with
+  `A` attempts performs at most `A` guarded operations and never materializes an
+  exponential schedule.
+
+## Commands
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```