smith-agents 0.4.5 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a4cd092162200b5cb861d9b9cd48069eab2e00beef71abf5fbfb91705c235ee
-  data.tar.gz: 483180aec2d6b6d63138324edfb10f564ca2c4ff800603eeb3a43807f4b20f95
+  metadata.gz: 986d706ecdf0a51035e20dde373106a6c6df18bc2150cae87e117993bd3fcd1e
+  data.tar.gz: e67ca0f8e6b4d6d35c5e1683876a9e191d0da92e29bee4c4379ca8b60b77c50e
 SHA512:
-  metadata.gz: 240e30a347d30d06063e57bece46ef646ce68c31463192a123cffd47858311ee1a92d6f7c664c519347775ff5df861e63ae8103005806cf39e400826b3e04c75
-  data.tar.gz: e478845f5665afeea75fb2b905dd4a7c48aa4ff56ca748661a1dc8302f44dacb029fa60117d900acfeca5558a52a9fde5bc8c7552a7a8149808b92b4898d1c82
+  metadata.gz: fa10aed2a7fc3874e8629af28beb07c230d5632b5a653630e70374931c8067775b8f17bee8c70a5c7e96c723e70dbad10c693491c37f8f4bb4a3c7f29b5aed1e
+  data.tar.gz: 13560c156073e79e1950d46e460a7f8a1a964a3af6d9b63b68394a0835b6b117f1fb60636c8cecb62d4fb6380e9064a535607cd2e57155e92f64915d2ab76228

data/CHANGELOG.md

@@ -6,6 +6,270 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Version
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-07-20
+
+### Added
+
+- Add a host-neutral durable composite lifecycle for same-agent parallel and
+  heterogeneous fan-out transitions. Smith emits immutable bounded plans and
+  inputs, executes one authorized branch through captured agent bindings, and
+  deterministically reduces a complete ordered outcome set through the normal
+  transition completion and failure paths.
+- Add exact transport contracts for ordered branch descriptors, redacted branch
+  failures, usage/tool/budget effects, and host-committed primary failure
+  selection. Composite branch retries remain explicitly unsupported; hosts own
+  scheduling, persistence, claims, fences, and incomplete-branch resumption.
+- Add compact selected-branch execution envelopes and stable host-declared agent
+  execution identities so workers do not receive the full plan and registry
+  replacement after planning fails closed.
+- Add scoped prepare, selected-branch execution, and reduction entry points so
+  process-local authority never crosses the supported public composite API.
+
+### Changed
+
+- Bump `Smith::EXECUTION_SEMANTICS_VERSION` to `2` so hosts invalidate generated
+  executable definitions when adopting the composite lifecycle.
+- Canonicalize aggregate branch output to the same JSON-compatible shape before
+  and after persistence.
+
+### Fixed
+
+- Preserve complete workflow, agent, and branch execution context across
+  nested parallel and heterogeneous fan-out work without leaking thread- or
+  Fiber-local Smith state.
+- Keep ordinary subclass setup and teardown extension points intact while
+  prepared execution seals framework-owned branch dispatch against subclass
+  replacement.
+- Restrict prepared execution authority to the exact coordinator or registered
+  branch Fiber, reject copied or serialized process-local authority, and make
+  activation, cleanup, and context restoration safe against asynchronous Ruby
+  thread interruption.
+- Keep composite planning and full-run validation linear in branch count, make
+  individual branch binding capture and validation constant-time in branch
+  count, reject the hard transport ceiling before descriptor allocation, and
+  incrementally enforce cumulative effect/output envelopes before consuming
+  execution authority.
+- Isolate decimal aggregation from host `BigDecimal` precision, reject aggregate
+  usage overflow, and preserve composite branch identity and retry
+  classification across persistence.
+- Bind one artifact execution namespace into every branch and the reducer,
+  reject aggregate budget overrun and known usage replay before consuming
+  authority, and validate cumulative persisted token/cost accounting.
+- Enforce complete canonical payload fields and encoded JSON byte limits before
+  returning transport values.
+- Allocate disjoint branch budget envelopes without exceeding the parent,
+  reconcile usage against branch-local token/cost consumption, bind branch
+  authority to one exact execution envelope, and prevent subclass collisions
+  from bypassing durable dispatch verification.
+- Reject forged retryability, untrusted error metadata, and unknown transport
+  keys without symbol interning; validate scalar and replay failures before
+  snapshotting tool effects.
+- Reject unknown transport enum values without symbol interning, reject corrupt
+  persisted branch-failure evidence instead of inventing defaults, enforce
+  cumulative encoded-effect bounds while streaming outcomes, and close active
+  branch authority before asynchronous interruption can escape a scoped call.
+
+## [0.5.0] - 2026-07-19
+
+This release contains intentional pre-1.0 public contract tightening and is a
+minor release rather than a `0.4.x` patch.
+
+### Added
+
+- Add configurable per-execution parallel branch/concurrency limits and a
+  shared finite exponential-backoff contract for workflow and persistence
+  retries.
+- Keep nested fan-out inside one bounded execution context across Fiber
+  boundaries, inherit outer cancellation, use only idle top-level workers, and
+  drain already-running branch work rather than detaching work or forcibly
+  killing threads with live resources. Add a configurable nesting limit,
+  hard-capped at 256, so recursive host composition fails before Ruby stack
+  exhaustion.
+
+- Add bounded host-coordinated session-message admission through
+  `Workflow#append_session_messages!`. Smith owns a canonical immutable copy,
+  serializes append against workflow execution, and returns an immutable
+  `MessageAdmission` digest witness while leaving persistence, idempotency,
+  session identity, and resume policy with the host.
+- Add opt-in restart-safe prepared-step recovery. Workflow classes bind a
+  host-supplied executable `definition_digest`; hosts submit an immutable typed
+  `PreparedStepRecovery.not_started` decision; Smith verifies the exact
+  committed preparation before reconstructing a guarded boundary.
+- Add exact-payload `replace_exact` and bounded `persistence_identity` adapter
+  capabilities. Restart-safe execution atomically advances the durable payload
+  from `prepared` to `dispatching` before transition work, preventing original
+  and recovered processes from both dispatching the same operation.
+- Separate restart-safe dispatch claim, commit confirmation, and transition
+  execution so transactional hosts can atomically correlate their attempt
+  ledger before any provider, tool, or deterministic step work begins.
+- Add immutable, bounded `PreparedStepDispatch` receipts. An exclusive host that
+  durably proves execution never started can reconstruct an exact committed
+  `dispatching` boundary without replaying its claim.
+- Add a generic process-local prepared-step execution authorization. Smith
+  verifies an exact preparation or dispatch without performing transition work;
+  a host may then commit its own executing-attempt record before consuming the
+  non-copyable, process-bound capability exactly once. Standard Marshal,
+  Psych/YAML, and JSON serialization hooks reject the capability.
+- Add `PreparedStepExecutionResult` so hosts can distinguish successful and
+  failure-routed transition attempts without inferring success from workflow
+  state.
+- Add strict bounded `PreparedStep.deserialize` transport decoding and the
+  typed `Sha256Hex` scalar. Prepared step counters are constrained to positive
+  signed 64-bit values for both Hash and JSON transports.
+
+- Expose `Workflow#pending_transition_name` so hosts can inspect the exact next
+  transition without serializing workflow state or traversing the graph.
+- Expose an immutable `Smith::Workflow::PreparedStep` descriptor for an active
+  strict split-step boundary. Hosts can persist opaque token, transition,
+  persistence-version, step-number, and preparation-digest identity without
+  reaching into workflow internals or copying Smith state.
+  `prepare_persisted_step!` retains its existing transition-name return value.
+- Compute descriptor identity before persistence dispatch with bounded,
+  canonical JSON hashing, preventing post-write validation failures and
+  unbounded preparation work.
+- Fence transactional split-step descriptors to an adapter-provided exact
+  transaction identity. `ActiveRecordStore` uses Rails' public
+  `current_transaction.uuid`; custom transactional adapters fail before writing
+  unless they expose an equivalent identity.
+
+### Changed
+
+- Make budget settlement receipt-based and one-shot. Reservation, reconciliation,
+  and release now fail closed on cross-ledger, replayed, unknown-dimension, or
+  amount-only settlement and publish aggregate state atomically. This tightens
+  the pre-1.0 ledger API and requires the next minor release.
+- Define budget scalar inputs as finite, non-negative `Integer` or `Float`
+  values and use exact internal decimal arithmetic so ordinary Float budgets do
+  not strand receipts or reject mathematically valid capacity. Ledger snapshots
+  remain JSON-safe numerics. This intentionally rejects opaque custom numeric
+  objects and non-JSON-safe numeric types at the boundary. Budget arithmetic is
+  isolated from and restores any host-configured `BigDecimal` precision limit;
+  `bigdecimal` is now an explicit runtime dependency.
+- Reject repeated or mixed primary transition declarations instead of silently
+  replacing an earlier execution primitive.
+- Treat named transition target-origin mismatches as graph errors rather than
+  warnings because runtime cannot execute the declared route from that state.
+- Constrain workflow topology identifiers to non-blank String or Symbol values,
+  matching runtime lookup, event, persistence, and graph-inspection semantics.
+- Reject oversized static fan-out declarations, non-finite or unschedulable
+  retry delays, and retry attempt counts above the configurable default limit
+  of 100 before executable work begins. This intentionally tightens previously
+  unbounded pre-1.0 declarations; hosts that require a higher finite attempt
+  bound must configure it before loading workflow classes.
+
+- Restore persisted workflow state without mutating caller-owned nested outcome
+  data while preserving Smith's symbolized runtime outcome contract.
+- Reject strict in-progress payloads before schema migration so a migration
+  cannot clear the uncertainty marker and replay a transition.
+- Keep an ambiguously acknowledged exact dispatch claim fail-closed in durable
+  `dispatching` state. Smith does not infer or replay an uncertain external
+  outcome.
+- Run Redis versioned and exact-payload CAS inside redis-rb's native
+  no-reconnect scope and do not replay either write after a transient
+  connection failure; a lost acknowledgement is outcome-unknown and must be
+  reconciled.
+- Pin the executable definition digest for the complete split-step boundary and
+  seal it on the workflow class when preparation or recovery authority is
+  acquired. Concurrent digest setters linearize before sealing or fail before
+  claim and execution.
+- Make Active Record exact replacement one conditional SQL update over key and
+  byte-exact payload while incrementing its optimistic-lock column. Validate
+  the database primary key or an unconditional single-column unique key index
+  through Active Record's table-keyed schema cache before each exact write.
+- Resolve callable Redis command clients as clients rather than factories, and
+  require a native reconnect-disabling scope before any Redis CAS begins.
+- Treat a persistence identity as available in doctor diagnostics only when its
+  value satisfies the same bounded non-empty contract used at runtime.
+- Revalidate workflow definition and transition identity when an execution
+  authorization is consumed. Capability release and execution are linearized by
+  exact identity so concurrent or stale holders cannot revoke or replay work.
+- Route an active prepared execution through a Smith-owned private-method
+  membrane, including reachable nested workflows. Subclass overrides retain
+  normal Ruby dispatch outside the authorized boundary but cannot substitute
+  retry, dispatch, guardrail, budget, or completion behavior during it. Nested
+  authority is limited to the root execution thread and revoked when that
+  execution closes, even when a host retains a child workflow instance.
+- Own String workflow identifiers at declaration time and keep graph snapshots
+  isolated from mutable caller aliases. Reject other topology object types at
+  the DSL boundary so graph lookup, event, and persistence semantics remain
+  consistent. The authorized
+  completion and failure boundaries bind Smith's implementation directly so
+  subclass method-name collisions cannot bypass typed result capture.
+- Capture exact direct, fan-out, optimizer, orchestrator, and reachable nested
+  agent bindings during authorization with bounded `O(V + E)` traversal. Later
+  mutable registry replacement cannot alter the authorized execution.
+  Same-agent parallel execution resolves its captured binding on the authorized
+  root thread and passes an identity-scoped class reference into worker
+  branches without leaking it into re-entrant workflows on the same thread.
+- Replace recursive graph reachability with an iterative walk over a graph-local
+  outgoing index. Existing graph snapshots remain isolated from later workflow
+  class mutation. State-reference validation and terminal-state metrics use
+  constant-time graph indexes. Nested runtime-readiness inspection uses an
+  iterative postorder traversal with workflow-class identity memoization and
+  cycle-edge diagnostics. Nested workflow contracts are captured and
+  revalidated before and immediately after child construction without repeated
+  full-transition scans.
+- Bound durable preparation comparison by canonical payload byte and node
+  limits, and preserve the legacy mutable step Hash while typed execution
+  results own an immutable, cycle-aware, bounded JSON-like snapshot. Result
+  validation now completes before successful workflow state mutation; invalid
+  provider output enters normal failure routing and returns a typed failure.
+  Hash keys are limited to owned String or Symbol values, and non-finite Floats
+  are rejected before success mutation.
+- Normalize top-level string keys in restored message Hashes before rebuilding
+  RubyLLM messages. Nested message content remains untouched so transport
+  decoding does not rewrite host payloads.
+
+- Maintain a declaration-time outgoing-transition index. First-transition and
+  terminal checks are constant-time; enumerating transitions from one state is
+  proportional to that state's outdegree. Stable declaration precedence,
+  subclass isolation, and transition redefinition semantics are preserved.
+- Custom adapters that report an open transaction now require
+  `transaction_identity` for strict split-step preparation. This intentionally
+  tightens the 0.4.5 boolean transaction contract so later unrelated
+  transactions cannot re-authorize a rolled-back descriptor.
+
+### Verification
+
+- Default suite: 1,304 examples, 0 failures on the final tree.
+- Runtime-hardening practical suite: 551 scenarios and 33,722 assertions across
+  graph reachability, retry/backoff, nested parallel execution, cancellation,
+  receipt-based budgets, hostile decimal precision, and asynchronous thread
+  interruption.
+- The built gem and its declared dependency set loaded under Ruby 3.2.2 and
+  Ruby 3.2.8; each runtime passed the same 551-scenario practical suite.
+- Downstream verification against the local checkout: Smith Runtime passed
+  1,188 runs and 6,287 assertions with 35 skips, plus 20 practical scenarios;
+  Smith Studio passed 1,848 runs and 13,851 assertions with one skip, plus 20
+  practical scenarios.
+- Message-admission and restore-input suite: 30 examples, 0 failures. A
+  44-scenario public-API matrix covered canonicalization, alias isolation,
+  bounded rejection, lifecycle contention, persistence round trips, and a
+  90,000-value near-limit message.
+- Focused graph, execution-authorization, binding-snapshot, typed-result, and
+  restored-message suite: 71 examples, 0 failures. All newly added files pass RuboCop;
+  the changed surface passes after excluding the repository's pre-existing
+  metrics baseline, and `git diff --check` passes.
+- Practical gem execution: 30 restart-safe scenarios covering serialized
+  preparation and dispatch recovery, exact-claim contention, corruption,
+  definition drift, ambiguous acknowledgements, and Active Record
+  commit/rollback coordination; a real redis-rb 5.4.1 run additionally proved
+  direct-client and factory resolution plus bounded multi-client exact-claim
+  contention.
+- Practical execution-authorization matrix: 30 public-API scenarios covering
+  success and handled failure variants, immutable graph snapshots up to 5,000
+  transitions, cyclic and shared result values, bounded rejection cases,
+  release, single-use authorization, copying, serialization, and concurrent
+  claims.
+- Additional practical hardening matrix: 20 public-API checks covering mutable
+  topology projection, 1,000/2,000/4,000-transition validation, 5,000-transition
+  reachability, a 1,200-workflow nested chain, shared-child memoization, cycle
+  diagnostics, root and nested execution membranes, and authorization
+  contention. Measured validation times were 5.80 ms, 12.80 ms, and 16.39 ms
+  respectively on the local Ruby 4.0.1 verification host.
+- A downstream host passed its serial and parallel suites against the
+  local Smith checkout and completed its practical direct-model boundary.
+
 ## [0.4.5] - 2026-07-11
 
 Patch release for generic host-coordinated workflow step boundaries and

data/README.md

@@ -17,7 +17,7 @@ environment before calling the slice complete.
 
 ```ruby
 # Gemfile
-gem "smith-agents", "0.4.5", require: "smith"
+gem "smith-agents", "0.5.0", require: "smith"
 ```
 
 ```bash
@@ -175,6 +175,12 @@ Smith.configure do |config|
   config.persistence_ttl = 1.day.to_i
   config.persistence_retry_policy = { attempts: 3, base_delay: 0.1, max_delay: 1.0 }
 
+  # 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
 
@@ -200,10 +206,21 @@ result = ReplyWorkflow.run_persisted!(
   key: "ticket:T-1042",
   adapter: Smith.persistence_adapter
 )
+
+# Admit host-supplied conversation input at a stable workflow boundary.
+workflow = ReplyWorkflow.restore("ticket:T-1042", adapter: Smith.persistence_adapter)
+admission = workflow.append_session_messages!(role: :user, content: "Continue")
 ```
 
+`append_session_messages!` validates and owns a bounded canonical copy of the
+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`;
+`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`):
 
@@ -214,7 +231,131 @@ Built-in adapters (all support TTL where the backend allows; `Redis`,
 - `:active_record` — keyed ActiveRecord model with an enabled optimistic-locking
   column for row-level CAS; Smith's logical version remains in the JSON payload
 
-See [`docs/PERSISTENCE.md`](docs/PERSISTENCE.md) for schema versioning, seed-drift validation, and the `idempotency_mode :strict` step-in-progress contract.
+See [`docs/PERSISTENCE.md`](docs/PERSISTENCE.md) for schema versioning,
+seed-drift validation, the `idempotency_mode :strict` step-in-progress contract,
+host-coordinated message admission, and opt-in restart-safe prepared recovery.
+Hosts that need to commit a durable attempt before provider or tool work can
+separate verification from execution with
+`authorize_prepared_step_execution!`, commit their own attempt ledger, and then
+consume the exact process-local capability through
+`execute_authorized_prepared_step!`. Smith does not own the host lease, attempt
+record, scheduler, or unknown-outcome policy. Authorization discovers the exact
+agent bindings reachable by that transition with a bounded `O(V + E)` graph
+walk, then resolves the bounded binding set in one registry epoch. A concurrent
+registry writer therefore cannot produce a mixed authorization containing
+bindings from two registry states or replace a captured binding between
+authorization and work. Every public Dry::Container mutation path participates
+in that epoch. Execution authorization accepts only concrete registered
+`Smith::Agent` classes; lazy container callbacks are not executed while
+authority is captured.
+While the capability is active, a host may call `each_agent_binding` with a
+block to inspect the exact captured `(registry_name, agent_class)` pairs before
+external work. Enumeration is process-local, performs no dispatch, and is
+rejected after release or consumption; it deliberately does not return a lazy
+enumerator that could escape the authorization scope.
+Reachable nested workflow transition contracts are captured and revalidated
+before child execution. The typed result owns a bounded snapshot of JSON-like
+Ruby values; unsupported mutable output values fail closed.
+During authorized execution, Smith also seals its private execution path against
+workflow subclass method-name collisions, including nested child workflows.
+Ordinary non-authorized runs retain normal Ruby override behavior.
+
+For `parallel: true` and `fan_out` transitions, a host can split one confirmed
+dispatch into independently scheduled branch operations without invoking agent
+classes outside Smith:
+
+```ruby
+preparation = workflow.prepare_composite_step!
+
+# Persist preparation.plan and preparation.input in host-owned records.
+# Each worker recovers the same confirmed dispatch and receives one descriptor.
+branch = preparation.plan.branches.fetch(0)
+execution = preparation.plan.execution_for(branch)
+outcome = branch_workflow.execute_prepared_composite_branch!(
+  execution:,
+  input: preparation.input
+)
+
+# After every branch has a terminal outcome, use another fresh recovery to
+# complete the Smith transition exactly once.
+result = reducer_workflow.reduce_prepared_composite_step!(
+  plan: preparation.plan,
+  input: preparation.input,
+  outcomes: ordered_or_unordered_complete_outcome_set,
+  primary_failure: host_committed_failed_branch_key
+)
+```
+
+Plans bind the exact prepared dispatch, host-supplied complete workflow
+`definition_digest`, execution-semantics version, prepared input digest, budget
+baseline, one shared artifact execution namespace, ordered branch identities,
+and explicit policies. Each plan, input, outcome, or effect payload is
+canonical, immutable, bounded to 1 MiB after JSON encoding, rejects missing or
+unknown fields, and redacts exception messages and backtraces.
+Reduction additionally bounds cumulative effects to 1 MiB and final aggregate
+output to 4 MiB before consuming execution authority. Reduction accepts either
+an `Array` or an `Enumerator`, validates each outcome incrementally, and stops
+as soon as a cumulative bound is crossed. The transport hard limit is 10,000
+branches; every recovered worker also enforces the current
+`Smith.config.parallel_branch_limit` before work.
+
+Planning is `O(B * D)`, where `D` is the bounded number of budget dimensions.
+The coordinator derives a compact selected-branch execution envelope in
+`O(D)` without copying the full branch collection. The scoped branch execution
+entry point captures and validates one selected binding in `O(D)` and constant
+time with respect to total branch count; the reducer validates the complete plan
+once. Reduction is `O(B + P log P)` in
+the worst case because canonical nested Hash ownership sorts keys, and uses
+`O(B + P)` bounded space.
+Smith does not persist plans or outcomes, select scheduling slots, claim work,
+choose an uncertain-outcome policy, or infer the primary failure. The host
+durably owns those decisions, gives each branch and reduction a separately
+recovered workflow instance, and must pass a complete outcome set. Transport or
+encoding faults become typed branch failures when Smith can preserve accounting
+evidence; otherwise the host must treat the worker result as uncertain and must
+not infer safe retry. Resume policy is incomplete branches only; per-branch
+retry is intentionally unsupported in this contract version.
+Composite payload digests prove canonical content integrity, not worker
+authenticity. Before reduction, the host must authenticate every outcome against
+its own claimed operation identity and current fencing token; those durable
+receipts remain outside Smith.
+
+The supported composite API is the three scoped workflow methods above plus the
+immutable transport values they return or accept: `Preparation`, `Plan`,
+`Input`, `Branch`, `BranchExecution`, `BranchOutcome`, `BranchFailure`, `Error`,
+`Effects`, and `Reduction`. Other constants under `Workflow::Composite` are
+implementation collaborators, not extension points or compatibility promises.
+
+Every agent used by this durable composite boundary must declare a stable
+host-computed SHA-256 execution identity. The identity represents the exact
+sealed executable asset the host intends to dispatch; Smith records it in the
+branch descriptor and rejects registry replacement after planning. Identities
+are deliberately not inherited because a subclass is a distinct executable
+implementation.
+
+```ruby
+class Researcher < Smith::Agent
+  execution_identity Digest::SHA256.hexdigest(generated_asset_manifest)
+  register_as :researcher, publish: false
+end
+
+Researcher.freeze
+Researcher.publish_registration!
+```
+
+Hosts that generate agent classes dynamically may call
+`register_as :name, publish: false` while constructing the class. This records
+the class identity without exposing it through `Smith::Agent::Registry`. After
+the host has validated and sealed the class, it may publish the exact class with
+`agent_class.publish_registration!`. Publication always uses the staged,
+immutable identity; callers cannot provide a second key. Registry collision and
+mutation epoch guarantees remain unchanged.
+
+Hosts that persist or cache generated executable definitions should include
+`Smith::EXECUTION_SEMANTICS_VERSION` in their definition identity. The gem
+version describes the package release; the execution-semantics version changes
+when Smith's executable workflow contract changes and must participate in host
+cache invalidation.
 
 ## Tools and Guardrails
 
@@ -240,6 +381,30 @@ end
 
 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:
+
+```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.
+
+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.
+
 ## Doctor
 
 After adding Smith, verify the integration:
@@ -296,6 +461,28 @@ When no classes are passed, `retry_on` uses `Smith::Errors.retryable?`.
 This is a bounded local transition retry policy. Durable scheduling, long waits,
 and external idempotency guarantees remain host-owned.
 
+## Runtime Complexity
+
+- Executable graph reachability is iterative `O(V + E)` time and `O(V)` space,
+  using indexed outgoing transitions and runtime-equivalent successor rules.
+- 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.
+
 ## Development
 
 Smith changes must not use brute-force graph search, validation, scheduling, or
@@ -309,5 +496,5 @@ bundle exec rspec
 bundle exec rubocop
 ```
 
-880 examples, MIT licensed. See [`CHANGELOG.md`](CHANGELOG.md) for the current
+1,175 examples, MIT licensed. See [`CHANGELOG.md`](CHANGELOG.md) for the current
 release surface.

data/docs/CONFIGURATION.md

@@ -105,6 +105,10 @@ end
 | `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_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 |
 | `trace_normalizer` | Emit `:normalizer_decision` trace events from `Smith::Models::Normalizer` | Useful when debugging cross-provider request shaping |
@@ -120,4 +124,3 @@ Add settings in this order:
 4. `config.pricing`
 
 Do not start by configuring every advanced switch at once.
-

data/docs/PATTERNS.md

@@ -234,10 +234,17 @@ end
 Why this is valuable:
 
 - Smith treats each branch as a real invocation
+- results preserve branch declaration order while active branch work is bounded by `parallel_concurrency`
 - workflow budgets remain cumulative outer limits
 - agent budgets still narrow each branch call
 - branch failures discard step output and route through normal failure handling
 - prepared input is reused consistently across branches
+- cancellation prevents queued branch bodies from starting and drains any
+  already-running branch before returning; branch adapters should use bounded
+  I/O and honor the cancellation signal
+- nested fan-out shares its top-level execution context and cancellation signal;
+  it uses only idle workers and falls back to its current worker when no capacity
+  remains, preserving the configured concurrency ceiling without pool deadlocks
 
 ## Example 6: Heterogeneous Fan-Out