smith-agents 0.8.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1fe948e343baa2573448f7a95a964729e96a71b0b2e6ef16226694400ba0fb97
-  data.tar.gz: 8f3d35e4ee6998ca41a4be0e19dcce0b5e843b44c0f28167aff3d5326d1be573
+  metadata.gz: b3692cc78203afacc91c1ede53a150d8bc864d8be5b9f549739570b5fe823dde
+  data.tar.gz: 6f9981471f8f8ddf2c6fb4141bfe2b6d8631bd21aaf78215c4c87d311aa6d3f2
 SHA512:
-  metadata.gz: 85bc7336ef0cb273979c4c7df1a4c0c724eb74cb34c4b49c1b23768e9454c700a1f33827ac9a1b33ff9680efd55b302b282db0fc553c5e20c52b4d13970044fa
-  data.tar.gz: afe1281c6ef7967292c1c43b7370ca5ab3795abcc98722aa8e10c03266347dcd2411d9c44878f1c0d4aa41df5f88ffd636d46084ff996f2008f60baa650ce5fc
+  metadata.gz: 870199be5d2163608606ab5a3eacca29c967e49e3f1f3fd193d88f4bdd57e455e973f03346b2b9769387b363c77147aaeb78a614837e4a665fca1fd4cfc66dc8
+  data.tar.gz: d555df7da59578922841547c53607a81ab7262a427d80a2140e3b9072158764cc33acca058a1fb380b20242315aa5161ca8659c7a26107e35527baa9efea9391

data/CHANGELOG.md

@@ -4,6 +4,439 @@ All notable changes to Smith are documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Smith is pre-1.0 and under active development; expect occasional contract tightening between minor versions until 1.0.
 
+## [0.11.0] - 2026-10-07
+
+### Added
+
+- `fallback_models` accepts a context block, matching the dynamic
+  `model { |context| ... }`. `fallback_models { |context| [...] }` is evaluated
+  once per agent invocation with the workflow context, and its entries pass
+  exactly the static form's validation: every entry needs an explicit
+  provider. An unqualified or invalid entry fails the step with
+  `Smith::WorkflowError` before any provider attempt, and that error is not
+  retried: `Smith::Errors.retryable?` is false for it, so a `retry_on` without
+  error classes, `retry_on Smith::AgentError`, and host retries built on
+  `Smith::Errors.retryable_classes` all leave it failed, unlike an invalid
+  `model` block result, which raises the retryable `Smith::AgentError`. The
+  chain keeps its de-duplication. Declaring entries and a block together raises
+  `ArgumentError`; a later static declaration clears the block and a later
+  block clears the static list; subclasses inherit the block. Graph
+  inspection, runtime readiness, and the doctor model check never call the
+  block: `fallback_models` returns `nil` for the block form and
+  `fallback_models_block` exposes the block. `resolve_fallback_models(context)`
+  evaluates the block, or returns the static qualified list (empty when none
+  is declared) when no block is configured. Resolution is `O(F)` time and
+  space for `F` returned entries. The static form is unchanged.
+- Every `:provider_call` trace carries `agent_name`, the registered name of
+  the agent that made the attempt (the value its usage entries carry), so a
+  generator and an evaluator sharing one `optimize` round, and so one
+  transition and round, stay apart; it is omitted for an unregistered agent.
+  When the provider reported usage, the trace also carries `input_tokens` and
+  `output_tokens`: the totals of the attempt's usage entries, covering a
+  successful completion, a failed attempt's completed tool-loop prefix, and
+  the usage a failed attempt's error reported. Both are omitted when the
+  provider reported none. A trace adapter can therefore record a complete
+  attempt when it ends instead of waiting for a step checkpoint. Token counts
+  are metadata, never content: `trace_content false` does not hide them.
+  Hosts with a `trace_fields` allowlist for `:provider_call` must add these
+  keys to receive them. The fields are documented in `docs/CONFIGURATION.md`.
+- `optimize`'s `before_eval` may reject a candidate. A returned Hash whose
+  `accept` (Symbol or String key) is `false` is that round's evaluation: it is
+  normalized and validated exactly as evaluator output (`feedback` required,
+  a numeric `score` when `improvement_threshold` is set), the evaluator is not
+  called for the round, and the loop continues as a rejection, so the
+  feedback reaches the generator's refinement turn and `on_exhaustion` applies
+  when rounds run out. Any other return value, including `nil` and a Hash
+  with `accept: true`, is ignored exactly as before and the evaluator judges.
+  A rejected round records only the generator's usage and `:provider_call`.
+  Documented in the Evaluator-Optimizer section of `docs/PATTERNS.md`.
+- `optimize`'s verdicts are an output. Each valid round's evaluation is
+  recorded as `{ round:, source:, verdict: }`: the optimizer round (the one
+  usage entries and traces carry), `:evaluator` or `:before_eval` for the one
+  that gave it, and the evaluation as normalized, every field the evaluator's
+  schema declares included, as a frozen copy. Once its loop has run, the
+  step's record carries its verdicts under `:evaluations` whether the step
+  completed or failed (a completion that fails after the loop, such as a split
+  step's snapshot, included), the verdict that ends the loop included, each
+  also naming its `attempt`, the retry policy's attempt that ran the loop: a
+  step `retry_on` runs again starts its loop afresh with rounds from 0, and the
+  earlier attempt's verdicts stay before the new ones. `RunResult#evaluations`
+  lists every optimize step's verdicts in step, attempt and round order as
+  frozen records with the step's `transition`, and
+  `OptimizationState#evaluations` gives a callable a frozen copy of its own
+  loop's verdicts so far. A step that failed before its loop, and every other
+  step, gains no key; a nested workflow's verdicts stay on its own run.
+  Verdicts are content, so no trace carries them, and like `steps` they
+  belong to the run that executed the step: nothing is persisted and a
+  terminal restore has none. Before this, a rejection's feedback lived only in
+  the loop and an accepted verdict was discarded, so a host could not see why
+  a candidate was sent back. Documented in the Evaluator-Optimizer section of
+  `docs/PATTERNS.md`.
+- `Smith::StepInProgressOnRestore` gains `state`, the persisted state the
+  interrupted step started from (a Symbol), and `transition`, the next
+  transition the payload records (such as a routed one), else `nil`, so a
+  host can tell which step died without reading Smith's payload. Both are set
+  wherever restore raises it and default to `nil` for any other construction;
+  the constructor stays backward compatible and the message gains only
+  ` state=...` when the state is known.
+
+### Changed
+
+- Contract tightening: an `optimize` round's verdict, now recorded as an
+  output, must hold JSON values only (Hashes with String or Symbol keys,
+  Arrays, Strings, Symbols, Integers, finite Floats, true, false, nil), and a
+  step's verdicts together must fit the limits a split step's record is held
+  to (`ExecutionResultSnapshot`'s depth, node and byte caps). A round whose
+  verdict breaks either, most likely a rejection `before_eval` returned
+  holding an object or a very large feedback, now fails the step with
+  `Smith::WorkflowError` at that round, in every run mode, keeping the
+  verdicts recorded before it. Before, such a verdict was never recorded and
+  the loop went on.
+- **Breaking:** a deterministic step's `write_outcome` is deep-symbolized
+  when written, matching restore. A live `RunResult#outcome_payload` (and
+  `RunResult#outcome`) now has Symbol keys at every depth, so a host reading
+  String keys from a live payload must switch to Symbol keys. Restored
+  payloads were already symbolized, so an outcome now reads identically live
+  and after a JSON restore. Persisted JSON is unchanged.
+- Contract tightening: `ActiveRecordStore` refuses to write with a non-nil
+  TTL instead of silently ignoring it, since it has no expiry column.
+  `store`, `store_versioned`, and `replace_exact` raise `ArgumentError`
+  before touching the database. Reads and deletes take no TTL, and resolving
+  the adapter never refuses, so `restore`, `persisted_state_exists?`,
+  `clear_persisted!`, `stuck_for?`, and `heartbeat_age` keep working while a
+  TTL is configured. A global or per-workflow `persistence_ttl` with this
+  adapter is refused by the initial checkpoint that `run_persisted!` and
+  `advance_persisted!` write before their first step, so no step runs before
+  the refusal. A nil TTL (the default) is unaffected. `smith doctor
+  --durability` fails a new `durability.ttl` check when the configured
+  adapter is an `ActiveRecordStore` and `Smith.config.persistence_ttl` is
+  set. The README, `docs/CONFIGURATION.md`, and the `persistence_ttl` DSL
+  comment no longer claim this adapter honours TTL.
+- Contract tightening: workflow and agent `budget` declarations raise
+  `ArgumentError`, naming the accepted keys, when given a key Smith does not
+  read; previously such a key was accepted and ignored. Workflow budgets
+  accept `total_tokens`, `token_limit`, `total_cost`, `tool_calls`, and
+  `wall_clock`; agent budgets accept `token_limit`, `cost`, `wall_clock`,
+  `tool_calls`, `total_tokens`, and `total_cost`. `wall_clock` is in seconds:
+  the README budget example used the ignored `wall_clock_ms: 30_000` and now
+  uses `wall_clock: 30`. The check is `O(K)` time and space for `K` declared
+  keys. State written by 0.10.0 keeps restoring after the host removes such a
+  key: 0.10.0 reserved every declared key at each agent call, so it could
+  persist a consumed entry like `"wall_clock_ms" => 0`, and restore now drops
+  consumed entries (String or Symbol keys) for dimensions the workflow no
+  longer declares. An undeclared dimension has no limit, so dropping it is
+  safe. The filter is `O(D + C)` for `D` declared and `C` consumed keys.
+
+### Fixed
+
+- `DeterministicStep#last_output` returned `nil` after a JSON restore,
+  because a restored session message carries a Symbol key with a String role
+  value. `last_output` now accepts a Symbol or String role under either key
+  form. Restored messages keep the shape 0.10.0 gives them (Symbol keys, JSON
+  values such as `role: "assistant"`).
+- Restored failures keep their type. `ProviderPermanentFailure`,
+  `BudgetExceeded`, and `GuardrailFailed` get their own failure families
+  (`provider_permanent_failure`, `budget_exceeded`, `guardrail_failed`) where
+  they were `other`, and restore as their own classes where they restored as
+  `RuntimeError`. `BlankAgentOutputError` keeps the `agent_error` family and
+  restores as itself where it restored as a plain `AgentError`.
+  `ProviderPermanentFailure` and `BlankAgentOutputError` gain `details` (each
+  value bounded to 512 bytes) and `from_details`, so `provider`, `model_id`,
+  `source_error_class`, `agent_name`, and `model_used` survive a restore.
+  Details stay JSON-normalized, and `FailureRecordValidator` rejects malformed
+  details, or one of these classes claiming another family, with
+  `Smith::PersistedFailureInvalid`. Records written by earlier versions (these
+  classes under `other`, or `BlankAgentOutputError` without details) keep
+  restoring exactly as before. The new families also appear as `error_family`
+  on failed `:transition` traces and `StepFailed` events. Composite branch
+  failure evidence (`Workflow::Composite::ErrorEvidence`) still classifies
+  these three errors as `other`. Rollback: 0.10.0 checks `error_family` and
+  `error_cause_family` against its own family list, so any persisted payload
+  whose `last_failed_step`, or its cause, carries one of the new families
+  fails to restore under 0.10.0, whether the run is terminal or not; clear or
+  settle such runs before rolling back.
+- A failed or aborted attempt's `:provider_call` trace now carries
+  `error_class`: the exception's class name, bounded to 512 bytes by the
+  diagnostic text helper (`anonymous_error` for an anonymous class). It also
+  carries `error_cause_class`, the class name of the error's direct cause
+  (`Exception#cause`, else the error's `wrapped_exception`), captured the same
+  way and omitted when there is no cause: a `Faraday::ConnectionFailed`
+  wraps both never-connected causes (`Errno::ECONNREFUSED`, `SocketError`,
+  `Net::OpenTimeout`) and lost-after-sending ones (`EOFError`,
+  `Errno::ECONNRESET`), and a host deciding whether an attempt may have been
+  billed needs to tell them apart. Messages never ride the trace. Hosts with a
+  `trace_fields` allowlist for `:provider_call` must add `:error_class` and
+  `:error_cause_class` to receive them.
+- `inject_state` injects only non-blank text. A formatter returning `nil` or
+  whitespace-only text no longer adds a bare `[smith:injected-state]` system
+  message, and when a formatter that returned text now returns blank, the
+  stale injected-state message is removed from session history. Injection
+  remains one linear scan over the session.
+- Restore and timestamp asymmetries. The `provider` in
+  `last_agent_execution`, read by `DeterministicStep#last_agent_provider`,
+  restores as the Symbol a live run holds where it restored as a String.
+  `created_at` is now written with microsecond precision (`iso8601(6)`), so a
+  `wall_clock` deadline no longer fires up to a second early; the early firing
+  affected live runs too, since the deadline is always computed from the
+  stored string. `updated_at` is written with the same precision at every
+  step, so it never reads earlier than `created_at`. Payloads with
+  whole-second timestamps still restore.
+- `optimize` sends a structured candidate (a Hash or Array from an
+  `output_schema` generator) to the evaluator, and replays it as the
+  refinement round's assistant turn, as JSON, using the serialization Smith
+  applies at the provider boundary, where it sent Ruby `inspect` notation.
+  String candidates are unchanged.
+- A budget reservation of the reported remaining amount no longer raises
+  `BudgetExceeded` far below the limit. `Budget::Ledger#remaining` returned
+  the Float nearest the exact remaining amount, and reserving it re-reads its
+  shortest decimal form, which after Float-priced costs sits above the exact
+  amount about half the time: a serial step on a $0.50 `total_cost` budget
+  failed its third call at $0.0707. `remaining` now returns a value that
+  never reads back above the exact amount, so it may read one ulp lower than
+  before. `Budget::Ledger#remaining_share(key, parts)` is a new public method
+  that returns one of `parts` equal shares that all fit, which fan-out branch
+  estimates now use (a `total_cost: 0.2` budget split across three branches
+  failed with nothing spent). Integers keep floor division; a Float steps
+  down in `O(1)` ulp steps. Amounts stay Integer or Float in and JSON-safe
+  numerics out.
+- `smith doctor`'s `persistence.capabilities` check reports an adapter that
+  fails to resolve as a failed "Persistence adapter configuration is invalid"
+  check carrying the resolution error, where it reported "No persistence
+  adapter configured".
+- A swallowed `on_step:` callback error is logged with its class after the
+  message (`Smith::Workflow on_step callback error: <message> (<class>)`),
+  where only the message was logged. It is still swallowed.
+
+## [0.10.0] - 2026-08-24
+
+### Added
+
+- Last-serial-agent-execution attribution. A deterministic (`compute`) step can
+  now read the model and provider that actually served the most recent serial
+  `execute :agent` step via `DeterministicStep#last_agent_model` /
+  `#last_agent_provider` (symmetric with `#last_output`, which returns that
+  step's content). The value is the resolved model/provider after fallback
+  resolution, so a step that failed its primary and completed on a
+  `fallback_models` entry reports the model that actually ran, never the
+  configured primary. It is durable lifecycle state (persisted in `to_state` as
+  `last_agent_execution`, restored across crash/resume), not a trace scrape, and
+  is `nil` until a serial agent step runs. Backward compatible: pre-upgrade
+  states have no `last_agent_execution` key and restore to `nil`; old readers
+  slice off the unknown key.
+
+### Fixed
+
+- Structured agent outputs recorded as session messages (Hash or Array
+  content) are now serialized to JSON at the RubyLLM provider boundary when
+  replayed to a later agent step. RubyLLM treats a Hash message content as
+  attachments and opens each value as a file, so replaying a prior structured
+  output to the next agent in a workflow session raised `Errno::ENOENT`. The
+  session store is unaffected: `last_output` and persisted `session_messages`
+  keep the raw structured value; only the provider-facing copy is serialized.
+
+## [0.9.0] - 2026-08-03
+
+### Upgrade notes
+
+- Rollback after running fan-out branches under this version is a one-way
+  door for those runs: composite branch effects written with attribution
+  values (usage entries) or batch-correlated `tool_call_id` capture entries
+  fail an older gem's exact-key validation at reduction or recovery.
+  Drain in-flight composite runs before rolling the gem back; plain
+  checkpoint payloads are unaffected (restored pre-attribution documents
+  re-serialize byte-identically, and old readers slice off unknown keys).
+- Hosts with a configured trace adapter see new output on upgrade without
+  any host change: one `:provider_call` line per provider attempt, one
+  `:cost` line per priced completed invocation, failed `:transition` lines
+  marked `outcome: :failed`, and ambient attribution keys (including
+  `execution_key`, the Smith persistence key) merged into every payload.
+  Identifier-only, but plan for the volume and shape change, especially
+  with `Smith::Trace::Logger` in production.
+- Hosts with a `trace_fields` allowlist for `:transition` must add
+  `:outcome` (and the error keys they want) or failed transitions render
+  indistinguishable from successes under the allowlist.
+- `Smith::Trace::Memory` is now bounded (default 10,000 entries, silent
+  drop with `dropped_count`); previously it accumulated without limit.
+
+### Added
+
+- Add `Smith::Attribution`, an immutable thread-local execution attribution
+  context (`execution_key`, `transition`, `from`, `to`, `branch_key`,
+  `round`). Workflow execution installs it per step (the `execution_key`
+  defaults to the persistence key of a persisted run), fan-out carries it
+  into branch threads and overlays the branch key, and evaluator-optimizer
+  rounds overlay the round index. Hosts can seed an outer scope with
+  `Smith::Attribution.with(execution_key: ...)` around non-persisted runs.
+  Restoration inside workflow execution rides `ThreadContextSnapshot`, which
+  now tracks the attribution thread key. Scope overlays are nil-ignoring
+  (`Context#merge`), but the per-step facts (`transition`, `from`, `to`)
+  are replaced verbatim, nil included (`Context#override`): a nested
+  child's `from`-less transition never inherits the parent step's `from`,
+  and the failed `:transition` trace keeps `from`/`to` present even when
+  nil for the same reason.
+- Merge ambient attribution fields into every `Smith::Trace.record` payload.
+  Attribution keys are identifiers, not content: caller-supplied keys win on
+  conflict, the content policy is unaffected, and a configured
+  `trace_fields` allowlist stays authoritative (add attribution keys to an
+  allowlist to receive them). Disable with `Smith.config.trace_attribution =
+  false` (default true).
+- Bound `Smith::Trace::Memory` (default 10,000 entries) with a
+  `dropped_count` reader and a `snapshot` method for readers racing
+  concurrent recording.
+- Tag `Workflow::UsageEntry` with the ambient attribution at recording time:
+  new optional members `transition`, `branch_key`, `round`, and `attempt_id`.
+  All four are nil on entries restored from checkpoints written by earlier
+  Smith versions and are omitted from serialization when nil, so restored
+  pre-attribution documents re-serialize byte-identically (hosts that digest
+  whole persisted documents in exact-mutation proofs depend on this). A
+  rolled-back gem drops the new keys from plain checkpoint payloads
+  (`from_h` slices to known members). Composite branch effects are the
+  exception: effects written by this version from a fan-out branch carry
+  real attribution values, and an older gem's exact-key effects validation
+  rejects them, so see the upgrade notes below before rolling back.
+  `recorded_at` now carries microsecond precision (`iso8601(6)`) on new
+  entries. Recording symbolizes `transition`/`branch_key` Strings exactly
+  as `from_h` does on restore, so a host seeding String attribution through
+  `Smith::Attribution.with` gets entries equal to their restored form.
+- Measure each provider attempt with a monotonic clock around the whole chat
+  completion (including any provider tool loop) and emit one
+  `:provider_call` trace per attempt (success or failure) carrying `model`,
+  `provider`, `duration_ms`, `attempt_id`, `attempt_index`, and `outcome`.
+  Every usage entry the attempt produced shares its `attempt_id` (an attempt
+  with an N-round tool loop records N entries): join there for the attempt's
+  single duration, never sum across entries. Gate with
+  `Smith.config.trace_provider_calls` (default true). `ProviderAttempt`
+  gains optional `attempt_id` and `duration_ms`.
+- Add a public read-only `Workflow#usage_entries` (frozen copy under the
+  recording mutex) so hosts can diff usage across a step boundary without a
+  full `to_state` serialization; `to_state` and `snapshot_usage_entries` now
+  read the ledger under the same mutex, so a state written mid-fan-out never
+  captures a torn array.
+- Thread real correlation identity through events: `Smith::Event#execution_id`
+  and `#trace_id` default to the ambient attribution execution key (the
+  persistence key during persisted runs) instead of a fresh random UUID per
+  event; the random fallback remains for events built outside any execution
+  scope. The `:tool_call` trace gains a nullable `tool_call_id` when the
+  invocation came from a provider batch (the tool-results capture entry
+  gains the same key under a later bullet in this release; composite
+  effects accept the extended shape with bounded value validation).
+
+- Emit from the step-failure paths, closing the success-only observation
+  gap: both `handle_step_failure` and the unresolved-transition handler now
+  record a `:transition` trace with `outcome: :failed` plus bounded
+  classification (`error_class`, `error_family` from FailureRecord's
+  taxonomy, `retryable`) and emit a new `Smith::Events::StepFailed` event.
+  Raw error messages never ride either; an emission failure is logged and
+  can never mask the original step error. The marker key is `outcome`
+  because `result` is a reserved content key in the trace pipeline. An
+  unresolved transition with no `:fail` transition still re-raises without
+  emitting: that path was never treated as a step. The unresolved handler
+  runs outside any step context, so it seeds the run identity explicitly;
+  both failure paths stamp persisted-run events with the persistence key.
+  Emission is terminal-per-step: a step that retries internally and then
+  succeeds emits only its `StepCompleted`; intermediate step-body retry
+  attempts stay dark at the step layer (provider-level failures remain
+  visible as `:provider_call` failure traces). `StepFailed` handlers run
+  outside the step snapshot's interrupt-masked region (emission is staged
+  in the failure rescue and flushed after the mask closes), interruptible
+  exactly like `StepCompleted` handlers. A step body that surfaces Smith's
+  own `UnresolvedTransitionError` emits exactly one `StepFailed` under the
+  real step identity; the unresolved handler recognizes the already-emitted
+  error instead of emitting a second event under the requested (never
+  executed) name.
+- Emit the long-advertised `:cost` trace: one per completed agent
+  invocation, whose value is the sum of that invocation's per-response
+  usage-entry costs. Summing per response is what tiered catalogs actually
+  bill; pricing the aggregate token totals as one call would resolve the
+  wrong tier for multi-response tool loops. Emitted only for fully metered,
+  fully priced invocations (a partially priced or partially metered
+  invocation emits nothing rather than presenting an incomplete figure);
+  gated by the existing `trace_cost` setting (the per-type gates live in
+  the built-in adapters; a custom adapter receives every type). `:cost`
+  traces are not a spend total: billed failed and partial attempts appear
+  only in usage entries. The same per-response sum now becomes
+  `agent_result.cost`, so budget settlement, result surfaces, recorded
+  entries, and the trace all agree on one invocation cost.
+- The OpenTelemetry adapter now creates retroactive spans with real
+  durations (span start backdated by `:tool_call` seconds or
+  `:provider_call` milliseconds; instant spans otherwise), preserves
+  numeric attribute types instead of stringifying everything, and uses only
+  the documented opentelemetry-api surface (`Tracer#start_span` with
+  `start_timestamp`, `Span#finish` with `end_timestamp`).
+
+- Add a `workflow` discriminator to the ambient attribution, every trace
+  payload, usage entries, and the `StepCompleted`/`StepFailed` events: the
+  emitting workflow's class name ("anonymous" when unnamed), so
+  nested-child graph facts are distinguishable from parent facts under the
+  shared root execution identity. Nil-omitted from serialized entries like
+  the other attribution members.
+- Every provider attempt now emits its `:provider_call` trace: `outcome` is
+  `:success`, `:failure` (provider failure, fallback may continue), or
+  `:aborted` (a non-provider error that re-raises), so prefix-accounted
+  usage entries always have their attempt join target.
+- The tool-results capture entry gains `tool_call_id` when the invocation
+  came from a provider batch (omitted otherwise, so direct-invocation and
+  pre-existing payloads keep their exact two-key shape); composite effects
+  accept the extended shape while still rejecting unknown keys.
+- `StepFailed` handlers now run outside the step snapshot's
+  interrupt-masked region: emission is staged in the failure rescue and
+  flushed after the mask closes with explicitly seeded run identity, so a
+  slow host handler can no longer make the workflow thread unkillable and
+  handlers match `StepCompleted`'s interruptibility.
+
+### Fixed
+
+- A user-declared `:fail` transition no longer inherits the early order
+  position of the auto-generated placeholder created by `state :failed`:
+  redeclaring a generated transition takes a fresh declaration position, so
+  it can no longer shadow a same-origin primary transition at run time.
+  Genuine user redefinitions keep their original position, and subclasses
+  inherit the bookkeeping.
+- Budget cost settlement now consumes the per-response priced sum instead
+  of pricing the invocation's aggregate token totals. Under linear pricing
+  the figures are identical; under tiered pricing the aggregate resolved
+  the wrong tier (or missed every tier and settled zero), so a
+  cost-budgeted workflow could keep spending after its real billed cost
+  exceeded the budget.
+
+### Removed
+
+- Remove the never-read `trace_retention` and `trace_tenant_isolation`
+  settings. Both were silent no-ops since introduction; reading or writing
+  them now raises, so a host relying on the illusion fails loudly instead
+  of silently.
+
+### Changed
+
+- Workflow step failure is now observable: subscribers to the events bus
+  receive `StepFailed` where previously failures emitted nothing (the
+  success-only scope is gone), and trace consumers see failed `:transition`
+  payloads distinguished by `outcome: :failed`.
+- `Workflow::Composite::Effects` validates usage-entry keys as
+  required-plus-allowed instead of exact: entries from an older producer
+  (missing the optional attribution keys) stay valid, current entries with
+  attribution pass, and unknown keys still reject. The optional keys are
+  bounded values, not just bounded keys: `transition`, `branch_key`, and
+  `workflow` must be non-empty Strings up to 256 characters, `round` a
+  non-negative Integer, and `attempt_id` a UUID when present. Tool results
+  accept the extended capture shape: `tool_call_id`, when present, must be
+  a non-empty String up to 1024 characters (`tool` keeps its exact prior
+  validation).
+
+
+- `Smith::Events` subscriptions now live in per-class buckets guarded by a
+  mutex: emit touches only the buckets for the event's ancestors instead of
+  scanning every subscription, dispatch order remains registration order,
+  and `is_a?` matching semantics are unchanged (instance-extended modules
+  dispatch through the singleton class; immediate values, which have no
+  singleton class and cannot be extended, dispatch through their class
+  ancestors). `Subscription#cancel` now
+  detaches from the registry, so cancelled subscriptions (including
+  `Events.within` scopes) no longer leak. Handlers run outside the registry
+  lock, so a handler may subscribe or cancel without deadlocking.
+- `Smith::Trace::Memory#record` and `#clear!` are mutex-guarded and safe
+  under parallel fan-out branches.
+
 ## [0.8.0] - 2026-07-25
 
 ### Added

data/README.md

@@ -217,10 +217,12 @@ message batch, appends it under Smith's workflow lifecycle lock, and returns an
 immutable digest witness. The host still owns session identity, transaction
 coordination, persistence, idempotency, and resume policy.
 
-Built-in adapters (all support TTL where the backend allows; `Redis`,
-`ActiveRecord`, and `Memory` support optimistic locking via `store_versioned`
-and exact dispatch claims via `replace_exact`; `ActiveRecord` participates in
-the caller's transaction for host-record coordination;
+Built-in adapters (all except `ActiveRecord` support TTL; `ActiveRecord` has no
+expiry column, so its writes refuse a non-nil `persistence_ttl`, while reads and
+deletes keep working and `smith doctor --durability` flags the combination;
+`Redis`, `ActiveRecord`, and `Memory` support optimistic locking via
+`store_versioned` and exact dispatch claims via `replace_exact`; `ActiveRecord`
+participates in the caller's transaction for host-record coordination;
 `Redis` and `Memory` also support heartbeat probes via `record_heartbeat` /
 `last_heartbeat`):
 
@@ -407,10 +409,16 @@ Guardrails run as input/output gates around agent calls. See [`docs/TOOLS_AND_GU
 
 ```ruby
 class BudgetedWorkflow < Smith::Workflow
-  budget total_tokens: 10_000, total_cost: 0.50, wall_clock_ms: 30_000
+  budget total_tokens: 10_000, total_cost: 0.50, wall_clock: 30
 end
 ```
 
+`wall_clock` is in seconds. 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`.
 
 Direct ledger integrations settle the exact receipt returned by reservation:
@@ -422,7 +430,9 @@ ledger.reconcile_many!(reservation, actual: { total_tokens: 640, total_cost: 0.0
 
 `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.
+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

data/docs/CONFIGURATION.md

@@ -83,8 +83,8 @@ Smith.configure do |config|
     tool_call: %i[tool duration]
   }
   config.trace_content = false
-  config.trace_retention = 86_400
-  config.trace_tenant_isolation = false
+  config.trace_provider_calls = true
+  config.trace_attribution = true
 
   config.pricing = {
     %w[openai gpt-4.1-nano] => {
@@ -115,16 +115,16 @@ observes a provider but finds only a model-only rate, it raises
 | `trace_transitions` | Emit transition traces | Usually leave on |
 | `trace_tool_calls` | Emit tool call traces | Usually leave on |
 | `trace_token_usage` | Emit usage traces | Useful for budget visibility |
-| `trace_cost` | Emit cost traces | Useful once pricing is configured |
+| `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_retention` | Trace retention policy hook | Useful when traces leave memory |
-| `trace_tenant_isolation` | Trace multi-tenant isolation flag | Enable in multi-tenant systems |
+| `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 |
 | `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_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` |
@@ -135,6 +135,26 @@ observes a provider but finds only a model-only rate, it raises
 | `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. 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

@@ -377,6 +377,65 @@ 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. 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

data/docs/PERSISTENCE.md

@@ -534,7 +534,11 @@ before writing when an open transaction has no exact identity capability.
 If execution raises or the process dies after external work, the durable marker
 remains set. A strict restore therefore fails closed with
 `StepInProgressOnRestore`; the host must reconcile operation results or classify
-the run as uncertain rather than blindly replaying the transition. The same
+the run as uncertain rather than blindly replaying the transition. The error's
+`state` is the persisted state the interrupted step started from (a Symbol) and
+its `transition` is the next transition the payload records, such as a routed
+one, or nil when it records none, so the host can tell which step died without
+reading Smith's payload itself. The same
 in-memory workflow object cannot retry an attempted transition. If a host
 transaction rolls back after a successful `persist!`,
 `complete_persisted_step!` rejects the rolled-back checkpoint. When the adapter