smith-agents 0.4.5 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a4cd092162200b5cb861d9b9cd48069eab2e00beef71abf5fbfb91705c235ee
-  data.tar.gz: 483180aec2d6b6d63138324edfb10f564ca2c4ff800603eeb3a43807f4b20f95
+  metadata.gz: 5f0194d534f9aa31c42dc14a0bd92a092f0088b3ac138ffe65060b00c6c564a0
+  data.tar.gz: 314f07b2e7c51f2372fec28cf7d495672ce38f4ba1f09a9af4cccba6f9cefd17
 SHA512:
-  metadata.gz: 240e30a347d30d06063e57bece46ef646ce68c31463192a123cffd47858311ee1a92d6f7c664c519347775ff5df861e63ae8103005806cf39e400826b3e04c75
-  data.tar.gz: e478845f5665afeea75fb2b905dd4a7c48aa4ff56ca748661a1dc8302f44dacb029fa60117d900acfeca5558a52a9fde5bc8c7552a7a8149808b92b4898d1c82
+  metadata.gz: f75713ef01aa104f3add7f6804dc8f77061ad12ea787598a16dce09bb0b08c23e256f35b346d4f3e53c99b86a0bdb5603ca6f7236dc66a1c60130a16ab9180a5
+  data.tar.gz: 28953ec750b620efff05055af313031eb24e97f6591dea4ea04b029d8c71d0a72de37d2aecb6ec78c532f73d3301d854b6f853bd26515abd98f93a5fe4668edb

data/CHANGELOG.md

@@ -6,6 +6,207 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Version
 
 ## [Unreleased]
 
+## [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,48 @@ 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.
+
+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 +298,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 +378,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 +413,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