smith-agents 0.10.0 → 0.12.0

data/UPSTREAM_PROPOSAL.md

@@ -138,6 +138,7 @@ What stays Smith-owned (orchestration concerns, not provider-API concerns):
 ## Tracking
 
 - RubyLLM PR #770 (OpenAI `/v1/responses` support) is the related upstream track. Smith's vendored `Smith::Providers::OpenAI::Responses` retires when #770 merges.
+- One divergence from #770 to carry upstream or keep on retirement: the vendored parser reports `input_tokens` with cached and cache-written input taken out (the SMITH-AUTHORED `response_usage`), as RubyLLM reports every other provider. #770 passes the Responses API's `input_tokens`, which includes cached input, while also reporting `cached_tokens`; Smith totals and prices both, so retiring the vendored file without this would count cached input twice. `spec/smith/workflow/cache_usage_spec.rb` parses a Responses body end to end to catch that.
 - This proposal (capability profiles + before_complete) is a separate, additive RubyLLM RFC. Once accepted, Smith files a migration PR to consume it.
 
 ## Current RubyLLM Docs Check

data/docs/CONFIGURATION.md

@@ -9,6 +9,7 @@ Use this for shared runtime services:
 - artifact backend
 - tracing
 - pricing catalog
+- run launcher (`run_launcher`, for child runs)
 - logger
 
 ### 2. Agent configuration: `Smith::Agent`
@@ -23,10 +24,14 @@ Use agent classes for invocation behavior:
 - `budget`
 - `guardrails`
 - `output_schema`
+- `output_contract`, `output_repairs`
+- `on_truncation`, `on_refusal`
 - `data_volume`
 - `fallback_models`
 - `register_as`
 
+The output macros are described in the README, Agent outputs.
+
 ### 3. Workflow configuration: `Smith::Workflow`
 
 Use workflow classes for orchestration behavior:
@@ -40,6 +45,9 @@ Use workflow classes for orchestration behavior:
 - `guardrails`
 - `context_manager`
 
+Transition steps that start runs of their own (`map`, `call`, `spawn`) need
+`Smith.config.run_launcher`; see the PERSISTENCE guide, Child Runs.
+
 ### If You Are Unsure Where Something Goes
 
 - "Which model should this agent use?" -> agent class
@@ -68,8 +76,14 @@ closed during agent configuration.
 
 ```ruby
 Smith.configure do |config|
-  config.artifact_store = Smith::Artifacts::Memory.new
-  config.artifact_retention = 3600
+  config.artifact_store = :s3   # S3 or R2; or :active_record, :file, :memory, a store
+  config.artifact_options = {
+    bucket: "smith-artifacts",
+    endpoint: "https://<account>.r2.cloudflarestorage.com", region: "auto",
+    access_key_id: ENV.fetch("R2_ACCESS_KEY_ID"), secret_access_key: ENV.fetch("R2_SECRET_ACCESS_KEY"),
+    request_checksum_calculation: "when_required", response_checksum_validation: "when_required" # R2
+  }
+  config.artifact_retention = 30 * 86_400
   config.artifact_encryption = :none
   config.artifact_tenant_isolation = false
 
@@ -86,12 +100,23 @@ Smith.configure do |config|
   config.trace_provider_calls = true
   config.trace_attribution = true
 
-  config.pricing = {
+  config.pricing = Smith::Pricing.validate_catalog!(
     %w[openai gpt-4.1-nano] => {
       input_cost_per_token: 0.0000001,
-      output_cost_per_token: 0.0000004
+      output_cost_per_token: 0.0000004,
+      cache_read_cost_per_token: 0.000000025
     }
-  }
+  )
+
+  # Streamed steps (`execute Agent, stream: :answer`): a callable that takes the
+  # step's info and returns its sink, or nil to stream nothing.
+  config.stream_sinks = { answer: ->(info) { AnswerStream.new(info[:execution_key]) } }
+
+  # 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.
+  config.budget_hold_ttl = 3600
 
   config.logger = Logger.new($stdout)
 end
@@ -99,16 +124,37 @@ end
 
 Provider-qualified model calls require provider-qualified pricing keys. Smith
 also accepts the string form `"openai/gpt-4.1-nano"`. Legacy model-only keys
-remain available only for calls whose provider is genuinely unknown; if Smith
-observes a provider but finds only a model-only rate, it raises
-`Smith::PricingConfigurationError` instead of silently undercounting cost.
+remain available only for calls whose provider is genuinely unknown; a
+provider-qualified call never reads a model-only rate, and usage with no
+applicable rate stays unpriced (a nil cost), without raising.
+`Smith::Pricing.validate_catalog!` is the raising check: it rejects model-only
+keys, keys that collide, non-Hash entries, optional rates that are not
+non-negative Integers or Floats, and a `batch_discount` that is out of range or
+sits inside a tier.
+
+Each entry, or each tier of a tiered entry, prices `input_cost_per_token` and
+`output_cost_per_token`, and optionally `cache_read_cost_per_token` and
+`cache_write_cost_per_token` for input read from or written to a prompt cache,
+which providers report apart from uncached input. A tier without its own cache
+rate uses the entry's. An entry may also carry `batch_discount`, the fraction
+taken off the cost of a call made in batch mode (`0.5` for half price). Cache
+rates and the batch discount are configured per catalog and count as `0` when
+absent: cache tokens then add nothing to a cost (the `:cost` trace says so with
+`cache_unpriced: true`), and a batch call costs the full rate. Tiers are chosen
+on a call's total input, uncached plus cache read plus cache write, so a cached
+call can pass every bounded tier and stay unpriced when the last tier is
+bounded. One cache write rate prices every cache lifetime; a provider that bills
+longer-lived cache writes higher (Anthropic's one-hour cache) needs the rate of
+the lifetime the host uses. Keys may be Symbols or Strings, as a catalog loaded
+from JSON or YAML has.
 
 ### What Each `Smith.configure` Setting Is For
 
 | Setting | What it controls | Typical first use |
 | --- | --- | --- |
-| `artifact_store` | Where large handoff payloads are stored | Start with `Smith::Artifacts::Memory.new` |
-| `artifact_retention` | Default retention window for artifact expiry checks | Set once you have a cleanup policy |
+| `artifact_store` | Where large handoff payloads and documents are stored: `:s3` (S3, R2), `:active_record`, `:file`, `:memory`, a store or a store class | Required outside `test_mode`; a shared, durable store whenever runs wait, retry or move between processes |
+| `artifact_options` | Options the named store is built with (`:s3`: `bucket:`, `prefix:`, `client:` or `region:`/`endpoint:`/credentials; `:active_record`: `model:`; `:file`: `dir:`; any: `namespace:`) | Set with `artifact_store` |
+| `artifact_retention` | Default retention window for artifact expiry checks | Longer than the longest wait of any run |
 | `artifact_encryption` | Metadata-level encryption policy flag | Leave at default until you wire a real backend |
 | `artifact_tenant_isolation` | Require namespaced artifact writes | Enable in multi-tenant systems |
 | `trace_adapter` | Where structural traces go | Use `Smith::Trace::Memory` or `Smith::Trace::Logger` first |
@@ -118,23 +164,63 @@ observes a provider but finds only a model-only rate, it raises
 | `trace_provider_calls` | Emit one timed `:provider_call` trace per provider attempt | Usually leave on |
 | `trace_cost` | Emit one `:cost` trace per completed agent invocation | Emits only once pricing is configured |
 | `trace_fields` | Allowlist structural trace fields | Use when you want tighter trace output |
-| `trace_content` | Whether content appears in traces | Leave `false` first |
+| `trace_content` | Whether content appears in traces: `false` drops content fields, `:redacted` replaces every String and Symbol inside them, at any depth, with `"[REDACTED]"`, and `true` keeps them. The built-in adapters treat `content`, `prompt`, `response`, `args`, and `result` as content; the central policy, which runs first, masks `args` and `result`. Every other field passes unmasked, including identifiers such as model, execution key (which defaults to the persistence key), tool name, and error class, and any field a custom trace adds: drop those with `trace_fields` if they must not leave the process | Leave `false` first |
 | `trace_attribution` | Merge ambient execution attribution into trace payloads | Usually leave on |
 | `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 |
+| `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) | Set when long-tail abandoned workflows accumulate in storage |
+| `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_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` |
 | `parallel_concurrency` | Maximum active branch threads within one parallel execution | Defaults to `8` |
 | `parallel_nesting_limit` | Maximum re-entrant fan-out depth; hard-capped at `256` | Defaults to `64` |
-| `test_mode` | Auto-select `:memory` adapter when `persistence_adapter` is nil | Enable in `spec_helper.rb` to skip Redis/cache wiring in tests |
-| `openai_api_mode` | `:auto` routes (gpt-5 family + tools + thinking) via `/v1/responses` using Smith's vendored Responses adapter (sync only; streaming over `/v1/responses` is not yet supported); `:off` drops incompatible tools instead | Leave `:auto` (default) unless you need streaming with the (gpt-5 + tools + thinking) combo, in which case set `:off` for graceful tool-dropping |
+| `test_mode` | Auto-select the in-process `:memory` adapter when `persistence_adapter` is nil, and an in-process artifact store when `artifact_store` is nil | Enable in `spec_helper.rb` to skip Redis/cache/bucket wiring in tests |
+| `openai_api_mode` | `:auto` routes (gpt-5 family + tools + thinking) via `/v1/responses` using Smith's vendored Responses adapter, which does not stream (a streamed step gets each reply as one delta); `:off` drops incompatible tools instead | Leave `:auto` (default) unless you need token streaming with the (gpt-5 + tools + thinking) combo, in which case set `:off` for graceful tool-dropping |
 | `trace_normalizer` | Emit `:normalizer_decision` trace events from `Smith::Models::Normalizer` | Useful when debugging cross-provider request shaping |
 | `ruby_llm_model_registry` | `:database` to require an AR-backed RubyLLM model registry; `:bundled` for the JSON fallback | Leave at default unless you've migrated to DB-backed |
 
+### The `:provider_call` Trace
+
+With `trace_provider_calls` on, every provider attempt emits one
+`:provider_call` trace when it ends: `model`, `provider`, `attempt_id` (shared
+with the attempt's usage entries), `attempt_index` (its position in the
+fallback chain), `outcome` (`:success`, `:failure`, or `:aborted`), and
+`duration_ms` once the timed call started. `agent_name` is the registered name
+of the agent that made the attempt, so a generator and an evaluator sharing an
+optimize round stay apart. `input_tokens` and `output_tokens` total the
+provider-reported usage that the attempt's usage entries record (a completed
+tool-loop prefix, and a failed attempt's own reported usage); both are omitted
+when the provider reported none. `input_tokens` counts uncached input only;
+`cache_read_tokens` and `cache_write_tokens` are the prompt-cache input beside
+it, and `thinking_tokens` are already inside `output_tokens`. `stop_reason` and
+`provider_message_id` are those of the attempt's last provider response, read
+from its raw body when the body is one Smith recognizes (Anthropic, OpenAI Chat
+Completions and Responses, Gemini, Bedrock Converse), or from its stream when
+the step streamed. Each of these is omitted when the provider did not report
+it. `mode` is `:stream` for a streamed attempt, `:batch` for one answered by a
+batch result, and omitted for a synchronous one; `request_changed: true` marks
+a batch result whose call rendered a request other than the one sent (a date in
+its prompt, data read afresh) and took the result all the same
+(`on_request_change: :keep`, the default). `:token_usage` and `:cost` traces carry
+`cache_read_tokens` and `cache_write_tokens` too, and `:cost` adds
+`cache_unpriced: true` when cache tokens were priced at 0 for lack of a rate. A
+failed or aborted attempt adds `error_class`,
+and `error_cause_class` for the error's direct cause (`Exception#cause`, else a
+wrapping error's `wrapped_exception`, such as the `EOFError` inside a
+`Faraday::ConnectionFailed`), omitted when there is none. Class names and token
+counts are metadata, never content: `trace_content false` keeps them, messages
+never appear, and a `trace_fields` allowlist for `:provider_call` must name
+each field it wants. Ambient attribution (`transition`, `round`, and so on)
+merges in as for every trace.
+
 ### Recommended First Additions
 
 Add settings in this order:

data/docs/PATTERNS.md

@@ -325,6 +325,16 @@ end
 What you get:
 
 - the child workflow's final output becomes the parent step output
+- a child that raises its failure passes the error to the parent step
+  unchanged, after its billable usage is rolled into the parent, so the
+  parent's `retry_on` and `Smith::Errors.retryable?` treat it as the child's
+  own error, at any nesting depth
+- a child that routes its failure through its own `on_failure` has handled it:
+  the parent step fails with a non-retryable `Smith::WorkflowError`
+  (`nested workflow failed: <child message>`, bounded to 1 KiB)
+- tool evidence travels up: when a tool ran in any of the child's steps, a
+  failure of the parent step becomes `Smith::ToolOutcomeUncertain` and is never
+  retried, exactly as when the tool runs in the parent step itself
 - parent step count stays parent-scoped
 - parent and child share the outer budget ledger
 - nested best-known token/cost totals roll up into the parent result
@@ -377,6 +387,66 @@ class TranslationWorkflow < Smith::Workflow
 end
 ```
 
+`before_eval: ->(state, context) { ... }` runs after each candidate is
+generated and before the evaluator is called, and may write to the workflow
+context (a new top-level key must be a Symbol that the context's `persist` list
+allows; see Deterministic Steps, Context writes). When it returns a Hash whose `accept` (Symbol or String key) is
+`false`, that Hash is the round's evaluation: Smith validates it exactly as
+evaluator output (`feedback` is required, and a numeric `score` when
+`improvement_threshold` is set), skips the evaluator for that round, and
+continues as a rejection, so the feedback reaches the generator's refinement
+turn and `on_exhaustion` applies when rounds run out. Convergence and the
+improvement threshold read it as they read evaluator output. Any other return
+value, including a Hash with `accept: true`, is ignored and the evaluator
+judges as before. A deterministic check that makes a candidate unacceptable
+can reject it this way without spending an evaluator call.
+
+Every round's verdict is an output. Once its loop has run, the step's record
+carries its verdicts under `:evaluations`, in attempt and round order, whether
+the step completed or failed (a step that failed before its loop, or any other
+step, has no such key), and `RunResult#evaluations` lists every optimize step's
+verdicts with the step's transition:
+
+```ruby
+result = TranslationWorkflow.new.run!
+result.evaluations
+# => [{ transition: :translate, attempt: 1, round: 0, source: :evaluator,
+#       verdict: { accept: false, feedback: "Keep the formal register.", score: 0.6 } },
+#     { transition: :translate, attempt: 1, round: 1, source: :evaluator,
+#       verdict: { accept: true, feedback: "ok", score: 0.93 } }]
+```
+
+`attempt` is the retry policy's attempt that ran the loop, from 1: when
+`retry_on` runs the step again, the loop starts afresh and its rounds count
+from 0 again, so an earlier attempt's verdicts, given and paid for all the
+same, stay before it, and an attempt that failed before its loop leaves a gap.
+`round` is the optimizer round, the one usage entries and traces carry.
+`source` is `:evaluator`, or `:before_eval` for a rejection `before_eval`
+returned. `verdict` is the evaluation as normalized (Symbol keys at every
+depth), with every field the evaluator's schema declares, not only the
+contract's. A verdict holds JSON values only (Hashes with String or Symbol
+keys, Arrays, Strings, Symbols, Integers, finite Floats, true, false, nil), as
+a provider's structured output does; anything else, most likely an object a
+`before_eval` returned, fails the step with `Smith::WorkflowError`, the same
+way in every run mode. So does a round whose verdict would take the step's
+verdicts past the limits a split step's record is held to (depth, nodes and
+bytes, `ExecutionResultSnapshot`'s), keeping the verdicts before it; a step's
+output counts toward those limits only in a split step. The records on the
+step and on `RunResult#evaluations` are frozen copies; a split step's
+execution snapshot hands the host its own mutable copy of the whole step,
+verdicts included. Only a valid verdict is recorded, and the one that ends the
+loop is kept, whether it accepts, converges, or trips the improvement
+threshold. A step whose completion fails after its loop (a split step's
+snapshot over its limits) keeps its verdicts on the failure record. A nested
+workflow's verdicts stay on its own run: the parent's step carries the child's
+usage, not its verdicts. A callable
+(`before_eval` or an exit mode) reads its own loop's verdicts so far from
+`state.evaluations`, a frozen copy without `attempt`, so it cannot rewrite the
+step's. Verdicts are content, so they are an output and never a
+trace: nothing about them reaches a trace adapter. Like `steps`, they belong to
+the run that executed the step, so a terminal restore has none; a host that
+needs them later stores them when the run returns.
+
 Why this matters:
 
 - the loop is explicit, bounded, and observable
@@ -397,11 +467,11 @@ Today that means:
 
 | Loop kind | Executable? | Smith primitive | Boundary |
 |---|---|---|---|
-| Retry | Yes | `retry_on` | Local transition retry only. Durable scheduling and idempotency stay with the host. |
+| Retry | Yes | `retry_on` | Local transition retry only. Durable scheduling stays with the host. A step that passes its idempotency keys (`docs/PERSISTENCE.md`, Replay Safety) sends every attempt's requests under the same keys, so a receiver that honours them can drop repeats. |
 | Evaluator-Optimizer | Yes | `optimize` | Bounded refinement inside one transition using structured evaluator output. |
 | Deterministic repair | Not native | Handwritten `compute` / `run` when exact semantics are owned by the workflow author. Deterministic route targets can be declared with `routes: [...]`. | No first-class repair contract or persisted repair counts yet. |
 | Guarded state re-entry | Not native | Handwritten `compute` / `run` may declare and route to named transitions with `routes: [...]`. | No Smith-owned entry-count ledger, re-entry guard contract, or mutation policy yet. |
-| Polling / wait | No | Host queue/timer plus Smith persistence helpers. | Smith must not model durable polling with sleeps, busy-waits, or `max_transitions` cycling. |
+| Wait for an event or a time | Yes | `await`, `delay` | Bounded by a required timeout; Smith records the wait and its deadline. Delivery (`resume!`), expiry scheduling (`expire_wait!`) and wake-up stay with the host. Smith must not model durable polling with sleeps, busy-waits, or `max_transitions` cycling. |
 
 Do not hide a durable wait or unbounded repair policy inside `compute` / `run`.
 Those primitives are synchronous deterministic steps inside the current workflow
@@ -409,7 +479,7 @@ runner. They are appropriate for local verification, normalization, failure
 classification, explicit routing, and bounded retry-adjacent checks; they are
 not a durable scheduler.
 
-If a host or compiler wants deterministic repair, polling/wait, or guarded
+If a host or compiler wants deterministic repair, polling, or guarded
 state re-entry as reusable graph contracts, the contract must be added explicitly
 before code generation claims executability. Deterministic `routes: [...]`
 annotations make handwritten route targets inspectable, but they do not by
@@ -519,17 +589,17 @@ Use `compute` for steps that check prior output and decide what happens next.
 
 ```ruby
 transition :verify_research, from: :gathered, to: :verified do
-  compute do |step|
+  compute(routes: %i[structure finish_terminal_failure]) do |step|
     if step.tool_results.any? { |t| t[:captured]&.dig(:retryable) }
       step.fail!("research temporarily unavailable", retryable: true)
     end
 
-    unless step.last_output
+    if step.last_output
+      step.route_to(:structure)
+    else
       step.write_outcome(kind: :terminal_failure, payload: { message: "no usable research output" })
       step.route_to(:finish_terminal_failure)
     end
-
-    step.route_to(:structure)
   end
 
   on_failure :fail
@@ -558,7 +628,9 @@ The yielded step object exposes a narrow, read-heavy surface:
 | `step.context` | `step.write_context(key, value)` |
 | `step.read_context(key)` | `step.write_outcome(kind:, payload:)` |
 | `step.last_output` / `step.output` | `step.route_to(:transition_name)` |
-|  | `step.fail!(msg, retryable:, kind:, details:)` |
+|  | `step.fail!(msg, retryable:, kind:, details:, new_idempotency_key:)` |
+| `step.idempotency_key(scope = nil)` | |
+| `step.attempt` | |
 | `step.tool_results` | |
 | `step.session_messages` | |
 | `step.current_state` | |
@@ -566,13 +638,17 @@ The yielded step object exposes a narrow, read-heavy surface:
 
 ### Behavior
 
-- **Routing**: `step.route_to` overrides `on_success`. If neither is set, normal state-based resolution applies. Named transitions that do not exist fail loudly with `WorkflowError`. When a deterministic transition declares `compute(routes: [...])` or `run(routes: [...])`, `step.route_to` must target one of those names; graph inspection validates the annotated targets before runtime.
-- **Failure**: `step.fail!` raises `Smith::DeterministicStepFailure` (extends `WorkflowError`) with `retryable`, `kind`, and `details` metadata. Routes through `on_failure` like any other step failure.
+- **Routing**: `step.route_to` overrides `on_success`, and can be called once per step. If neither is set, normal state-based resolution applies. Named transitions that do not exist fail loudly with `WorkflowError`. When a deterministic transition declares `compute(routes: [...])` or `run(routes: [...])`, `step.route_to` must target one of those names; graph inspection validates the annotated targets before runtime.
+- **Declared routes must be taken**: a step that declares `routes:` and finishes without `step.route_to` raises `Smith::UnroutedDeterministicStep` (a `WorkflowError`, so `on_failure` applies and no write is kept) when its target state has an outgoing transition, unless the transition declares `on_success` or `compute(routes: [...], fallthrough: true)`. A step whose target state has no outgoing transition may finish unrouted: the run ends there, as declared, so `compute(routes: [:fail])` can name only its exceptional route. Graph inspection follows the same rule: such a step reaches its routes and its `on_success`, and the first transition from its target state only with `fallthrough: true`; a transition reachable only that way is reported unreachable until the step declares `fallthrough: true`. `fallthrough: true` without `routes:` raises `WorkflowError` at definition time. A class-less `retry_on` does not retry `UnroutedDeterministicStep`, but `retry_on Smith::WorkflowError` does, until its attempts run out.
+- **Failure**: `step.fail!` raises `Smith::DeterministicStepFailure` (extends `WorkflowError`) with `retryable`, `kind`, `details` and `new_idempotency_key` metadata. Routes through `on_failure` like any other step failure. `new_idempotency_key: true` declares that this step's own requests in the attempt took no effect, so this step's `retry_on` sends them under new keys; it never moves an enclosing workflow's retry.
+- **Idempotency keys**: `step.idempotency_key(scope = nil)` is a key for a request the step sends outside the system, the same on every attempt of the step and after a restore, unique to the run, the step and the scope. `step.attempt` is the attempt under way, from 1. See `docs/PERSISTENCE.md`, Replay Safety.
 - **Outcome**: `step.write_outcome(kind:, payload:)` stores a workflow-owned terminal payload without smuggling it through context. The payload is persisted with the workflow and surfaced on `RunResult.outcome`, `RunResult.outcome_kind`, and `RunResult.outcome_payload`.
+- **Context writes**: `step.write_context(key, value)` takes a Symbol key. The value is stored at the call in the context's key shape: every Hash key at every depth becomes the Symbol of its String form, which is what a restore produces, so `step.read_context` later in the same step, the next step, and a restored run all read the same keys. Values are not converted (see `docs/PERSISTENCE.md`). Two keys that become the same Symbol, a value that contains itself, or nesting deeper than 100 levels fail the write with `Smith::WorkflowError`.
+- **Persist list as an allow-list**: when the workflow's `Smith::Context` declares `persist :a, :b`, writing any other key raises `Smith::UndeclaredContextKey`, in every run, persisted or not and nested or not, so the list is the context's declared shape rather than a filter applied at checkpoints. A rejected write fails the step even when the step body rescues the error. With `persist :auto`, or no `persist` declaration, any Symbol key may be written. Hooks that receive the live context (`before_eval`, `after_completion`, guardrails) are held to the same rules at the end of their step: a new top-level key must be a Symbol the list allows, a violation fails the step and puts the context's top-level values back as they were when the step started, and new or replaced values take the context's key shape.
 - **Context reads**: `step.context` returns an isolated snapshot of the workflow context at step start. Mutating that snapshot does not mutate workflow state. `step.read_context(key)` returns a merged view — pending `write_context` values override the snapshot. Use `read_context` when you need read-after-write coherence within the same step.
 - **No output**: Deterministic steps produce no session message output. `last_output` continues to mean the last agent output.
 - **No budget**: No tokens or cost consumed.
-- **Persistence**: Context writes and written outcomes survive `to_state`/`from_state`. The block itself (a Proc) lives on the class-level Transition and is never serialized.
-- **Trace**: Emits `:deterministic_step` traces for start, success/routed, and failure. When a step writes an outcome, the trace includes `outcome_kind`.
+- **Persistence**: Context writes (always to a persisted key, see above) and written outcomes survive `to_state`/`from_state`. The block itself (a Proc) lives on the class-level Transition and is never serialized.
+- **Trace**: Emits `:deterministic_step` traces whose `outcome` is `:started`, `:success`, `:routed`, or `:failed` (`outcome`, not `result`, which the content policy strips). A failure carries `error_class`, `error_family`, and `retryable` when known, never the error message. When a step writes an outcome, the trace includes `outcome_kind`.
 - **Mutual exclusivity**: `compute` and `run` cannot be combined with `execute`, `route`, `workflow`, `optimize`, or `orchestrate`. A transition declares exactly one primary execution body.
 - **No hidden scheduler**: `compute` and `run` execute synchronously inside the current runner. Use them for bounded deterministic logic, not for durable polling or wake-up loops.