ruby_llm-browser 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 20b730312da9ae14b8e3a17d386ecaa0034a38b1ac87515e89d2c6a4aa29e8d7
-  data.tar.gz: 7f27467a067bbf8e8712cfffe1a855ce85a21e563765658a142ca7c468297929
+  metadata.gz: 6c1e32269fa76e278df596a6e63e30d28506a9e7e3ada269703bad06ba870fef
+  data.tar.gz: d103e32333352508883d3794dd6e37a4aa3058d4f2e5842ccd174c6b2b43b11e
 SHA512:
-  metadata.gz: ec5d0517a3b4fa4b4fbd2a440fd52d59b173b2f2adb4674c96f9e667bbaa57276984f09f1292865adb662fc1595f9f73b63c32509b9bd9269a058366bfa24ce0
-  data.tar.gz: 13fea67455f9bdd9b49864752e69731b527958fbf06bd7ca0325a167345eaf115190cff9778247e8e526518fdef0b17c1fcb46f60346ab5c09508ca490f8cb35
+  metadata.gz: 39769537e3c05f25231657f2b56ab72bda7690ac2b7e144149cac85a8d2d7de7b29e73f45a4dd41fe8e6718aa0f1535d6c2d77d5f4203469474b4a64e018dc4d
+  data.tar.gz: 1ff61fb1a7fe9017be814634d6763938e6a6652814df76386b43ca90217f2ffad2f51429a5edec1855a431300802182c8d2ad7c9a9eb00890a6612ba9ccd7da4

data/CHANGELOG.md

@@ -4,6 +4,25 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project aims to
 follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-10-19
+
+### Added
+
+- Opt-in `Rails.result_delivery` receives a sanitized `Result` and its operation
+  after execution and cleanup. Hosts own persistence, authorization and recovery.
+- `Rails::ResultDeliveryError` reports failed delivery with retained in-process
+  operation/result objects. Callback errors do not leak through exception causes.
+- A runnable host-owned SQLite result store and separate-process Active Job example,
+  with scoped reads, idempotent writes, failure recovery and worker-crash tests.
+- Upgrade coverage against the frozen 0.2.0 migration with existing records retained.
+
+### Fixed
+
+- Copy and freeze `Result` identity and error strings so constructor-input mutation
+  cannot alter a retained result. Mutating these result attributes raises `FrozenError`.
+- Suppress result delivery from cancelled or fenced workers. A delivery failure
+  preserves session state; duplicate jobs never repeat browser work or delivery.
+
 ## [0.2.0] - 2026-10-19
 
 ### Added

data/README.md

@@ -3,7 +3,7 @@
 An unofficial [RubyLLM](https://rubyllm.com) extension for read-only browser inspection
 and schema-checked extraction, with an optional Rails 8 adapter.
 
-**0.2.0 supports offline use only.** `FakeBackend` runs without credentials or network
+**0.3.0 supports offline use only.** `FakeBackend` runs without credentials or network
 requests. The experimental Stagehand adapter refuses live operations; `Act` is an
 offline simulation. This project is not maintained or endorsed by RubyLLM or Browserbase.
 
@@ -16,7 +16,7 @@ offline simulation. This project is not maintained or endorsed by RubyLLM or Bro
 Use Ruby 3.2+ and RubyLLM 2.x. Add to your Gemfile, then run `bundle install`:
 
 ```ruby
-gem "ruby_llm-browser", "~> 0.2.0"
+gem "ruby_llm-browser", "~> 0.3.0"
 ```
 
 ## Try it offline

data/docs/README.md

@@ -8,6 +8,7 @@ the gem.
 - [Getting started](_getting_started/getting-started.md): installation and an offline example.
 - [Configuration](_getting_started/configuration.md): host inputs and process defaults.
 - [Inspect and Extract](_core_features/inspect-extract.md): tools and result handling.
+- [Rails result delivery](_advanced/result-delivery.md): host storage, access checks, and delivery recovery.
 - [Rails jobs and recovery](_advanced/rails-integration.md): installation, workers, and cleanup.
 - [API and configuration reference](_reference/api-and-configuration.md): parameters and errors.
 - [Security model](SECURITY_MODEL.md): guarantees and limits.

data/docs/RELEASING.md

@@ -17,6 +17,10 @@ After reading this guide, you will know:
 
 ## Compatibility evidence
 
+The source repository's `docs/evidence/V0_3_VALIDATION.md` records local 0.3.0 checks.
+`docs/evidence/V0_3_RELEASE.md` records the exact remote CI, published artifact and
+hosted documentation results. The earlier audit below is historical evidence.
+
 The 2026-10-18 audit runs on Ruby **3.3.5**, arm64 macOS, with Stagehand **3.21.0**,
 JSONSchemer **2.5.0**, and sqlite3 **2.10.0**. Full offline suites cover:
 
@@ -40,6 +44,7 @@ bundle exec rake
 bundle exec bundle-audit check --update
 bundle exec ruby examples/plain_ruby.rb
 bundle exec ruby examples/rails_adapter.rb
+bundle exec ruby examples/rails_results.rb
 
 BUNDLE_GEMFILE=gemfiles/ruby_llm_2_0.gemfile bundle install
 BUNDLE_GEMFILE=gemfiles/ruby_llm_2_0.gemfile bundle exec rspec
@@ -77,10 +82,10 @@ Verify all of the following:
 - Core require loads no Rails, Active Record, Active Job, or Stagehand client.
 - The optional Rails require loads on demand.
 - The generated migration and all README-linked guides are shipped.
-- Both examples run using the installed artifact.
+- All shipped examples run using the installed artifact.
 - The artifact contains no keys, cookies, dumps, databases, lockfiles, or test fixtures.
 - Dependency/license inventory and known-advisory check match the resolved versions.
-- Record the artifact SHA-256, exact versions, commands and date in the WORK ledger.
+- Record the artifact SHA-256, exact versions, commands and date in the candidate validation note.
 
 ## Release boundaries
 
@@ -114,12 +119,12 @@ section and run `bin/verify-release` without that flag. The tag workflow require
 released metadata; local candidate verification cannot enable publication.
 
 Run the checks above, review the package contents and push the completed commit to
-`main`. Then create and push a matching tag, for example `v0.2.0` for gem version
-`0.2.0`:
+`main`. Then create and push a matching tag, for example `v{{ site.version }}` for gem version
+`{{ site.version }}`:
 
 ```bash
-git tag -a v0.2.0 -m "Release 0.2.0"
-git push origin v0.2.0
+git tag -a v{{ site.version }} -m "Release {{ site.version }}"
+git push origin v{{ site.version }}
 ```
 
 The `Release Gem` workflow rejects a tag that does not match both the gem and docs

data/docs/_advanced/development-and-testing.md

@@ -28,6 +28,13 @@ the RubyLLM 2.0 and Rails 8.0 alternate bundles, and the plain-Ruby and Rails ex
 Install each alternate bundle first if needed. Database suites run sequentially.
 RuboCop uses the writable `tmp/rubocop` cache. Default tests block unmocked HTTP.
 
+The Rails result suite executes serialized jobs in separate processes against temporary
+SQLite files. It verifies reads after worker exit, actor/run isolation, conflicting
+delivery rejection, persistence failures before and after commit, and the crash gap
+between browser execution and host storage. HTTP stays blocked in those subprocesses.
+A frozen 0.2.0 migration verifies preservation of existing rows and indexes. These
+checks exercise host result delivery without adding a second browser fixture.
+
 Commit each completed change with its docs and checks. Keep the next work item in the
 [roadmap]({% link _reference/roadmap.md %}); do not create a second task ledger.
 

data/docs/_advanced/rails-integration.md

@@ -15,6 +15,7 @@ After reading this guide, you will know:
 
 - How to install the adapter's tables.
 - How to build a freshly authorized job context with matching budgets.
+- How to deliver results to host storage.
 - How to inspect status, cancel work, and recover orphaned sessions.
 
 ## Installing the adapter
@@ -103,9 +104,12 @@ summary = operation.summary
 
 `summary` omits provider session IDs and budget internals. It reports state, steps,
 bytes, fence, timestamps, error code and cancellation flag. It is coarse progress,
-not a percentage-complete promise. No result body is durably stored by the job; the
-host must explicitly implement authorized result storage/delivery if needed. Do not
-rely on an Active Job return value after asynchronous execution.
+not a percentage-complete promise. To persist a result body, opt in to
+`RubyLLM::Browser::Rails.result_delivery`. The callback receives `operation:` and
+`result:` after execution and cleanup. Your application owns storage and authorized
+retrieval. Read [Rails result delivery]({% link _advanced/result-delivery.md %}) for
+failure handling and recovery. Do not rely on an Active Job return value after
+asynchronous execution.
 
 The stores are trusted server APIs, not tenant-safe controllers. They expose unscoped
 fetch/sweep methods for workers; never expose them directly to model arguments or HTTP.

data/docs/_advanced/result-delivery.md

@@ -0,0 +1,119 @@
+---
+layout: default
+title: Rails Result Delivery
+nav_order: 2
+description: Persist sanitized background results in your application and recover delivery separately from browser cleanup.
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+
+After reading this guide, you will know:
+
+- How to receive a background operation's bounded result.
+- How to store and authorize results in your application.
+- How to recover delivery without repeating browser work.
+
+## Persist a Result
+
+Configure the optional Rails adapter and its context factory first. See
+[Rails jobs and recovery]({% link _advanced/rails-integration.md %}). Register a trusted
+callback in your initializer:
+
+```ruby
+RubyLLM::Browser::Rails.result_delivery = lambda do |operation:, result:|
+  # Your host service persists result.to_h with operation.id, actor_id and run_id.
+  BrowserResults.persist(operation: operation, payload: result.to_h)
+end
+```
+
+`BrowserResults` is your application service. It is not a gem class. The callback
+receives an immutable `Operation` snapshot and the core's sanitized, bounded `Result`.
+Persist `result.to_h` or `result.to_json`, rather than the operation object, which
+contains a provider session ID for trusted bookkeeping.
+
+The callback runs synchronously in the worker after the engine attempts cleanup and
+before the job returns. It receives successful, truncated, error, unknown, and
+cleanup-pending results. Preflight exceptions have no `Result` and do not invoke it.
+Cancellation or a changed fence detected after execution suppresses delivery. A
+missing, already started, or terminal operation does not invoke it either.
+
+The default is `nil`, which preserves the existing job return behavior. Setting the
+hook to a non-callable value raises `InvalidInput`. Callback return values are ignored;
+raise an exception if persistence fails.
+
+## Keep Storage and Access in the Host
+
+Run the disposable, offline host example:
+
+```sh
+bundle exec ruby examples/rails_results.rb
+# RESULT_AFTER_WORKER_EXIT_PASS
+# SCOPED_READS_PASS
+# IDEMPOTENT_WRITE_PASS
+```
+
+It writes a serialized Active Job to a temporary file, executes it in a separate
+worker, waits for exit, and reads the schema-checked extraction from SQLite. Repeating
+the job in another worker starts no browser session. The example's host table accepts
+identical repeated writes and rejects conflicting bodies or actor/run identities.
+Its file queue holds one job and is for demonstration; use a durable queue in your
+application. The temporary database and queue file are removed on completion. Read
+[the example source](https://github.com/yorzi/ruby_llm-browser/blob/main/examples/rails_results.rb).
+
+Use a unique operation ID for idempotent writes. Repeating a write of the same result
+should succeed; reject a conflicting body or actor/run identity. Retrieve with the
+authenticated actor and run in the database query. Never use model-supplied actor IDs
+as authorization. Recheck host revocation and retention rules when serving a result.
+
+The gem creates no result table and adds no migrations. Keep results in your host's
+database or durable storage. Do not rely on an Active Job return value or in-memory
+callback state after a worker exits.
+
+An `ok` extraction passed the pinned schema before redaction and bounding. A truncated
+result can contain a preview instead of the original schema shape. Treat all page
+content as untrusted. Store failures too, without interpreting `cleanup_pending` or
+`unknown` as success. A stored result describes that attempt; a later reaper changes
+session state, not the historical result body.
+
+## Recover Delivery Separately
+
+If the callback raises, the job raises `RubyLLM::Browser::Rails::ResultDeliveryError`
+with code `RESULT_DELIVERY_FAILED`. The original callback exception is not chained,
+so automatic job logs cannot print its potentially sensitive message. The error
+exposes `operation` and `result` to trusted, in-process host recovery code:
+
+```ruby
+# Inside host code that catches ResultDeliveryError while these objects still exist:
+RubyLLM::Browser::Rails.result_delivery.call(
+  operation: error.operation, result: error.result
+)
+```
+
+This retries only your callback. Reauthorize recovery in the host. Keep external side
+effects idempotent and persist the result before sending notifications. For durable
+notification retries, write the result and a host outbox entry in one transaction.
+An exception object does not survive worker exit as durable result storage.
+
+A failed callback does not change the operation's session state or error code. Queue
+redelivery of `OperationJob` does not repeat a started browser operation and does not
+redeliver its result. Keep delivery failures visible in your job monitoring; retrying
+the browser job is not a result-recovery mechanism.
+
+There is no atomic transaction across provider execution, operation bookkeeping, and
+host persistence. A process crash after execution but before persistence can lose the
+result. The hook offers one automatic delivery attempt, not guaranteed or exactly-once
+delivery. If host storage is unavailable, a recovery handler must save the retained
+result to a separate durable destination before it exits. Never recover a lost result
+by replaying an uncertain browser operation automatically.
+
+Cancellation can race after the worker's final check. If your host forbids storing a
+result after revocation, enforce that rule in the persistence transaction as well as
+at read time. A callback failure must not clear cancellation, pending cleanup, or quota.
+
+## Next Steps
+
+Read [the API reference]({% link _reference/api-and-configuration.md %}) for result
+fields and [Rails jobs and recovery]({% link _advanced/rails-integration.md %}) for
+cancellation and reaper behavior.

data/docs/_config.yml

@@ -108,6 +108,6 @@ code_language: ruby
 # and {{ site.examples.NAME }}. Candidates remain unreleased; the docs builder
 # reads stable docs from the latest release tag and main under /next/.
 released: true
-version: "0.2.0"
-stable_version: "0.2.0"
+version: "0.3.0"
+stable_version: "0.3.0"
 examples: {}

data/docs/_data/navigation.yml

@@ -9,6 +9,6 @@
   collections:
     - reference
 - title: "What's New"
-  url: /whats-new-in-0-2/
+  url: /whats-new-in-0-3/
 - title: Releases
   url: https://github.com/yorzi/ruby_llm-browser/releases

data/docs/_getting_started/overview.md

@@ -50,3 +50,6 @@ does not click or submit forms.
 * [Getting Started]({% link _getting_started/getting-started.md %}) - install and run the offline example.
 * [Configuration]({% link _getting_started/configuration.md %}) - choose host-owned defaults.
 * [API and configuration reference]({% link _reference/api-reference.md %}) - see options, statuses, and result fields.
+
+Read [Rails Result Delivery]({% link _advanced/result-delivery.md %}) to persist a
+background result in host storage and recover delivery separately from session cleanup.

data/docs/_getting_started/whats-new-in-0-3.md

@@ -0,0 +1,48 @@
+---
+layout: default
+title: What's New in 0.3
+redirect_from:
+  - /whats-new/
+nav_order: 4
+description: Deliver Rails background results to host storage without repeating browser work on delivery failure.
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+
+After reading this guide, you will know:
+
+- How to persist the result of a background operation.
+- Which delivery failures your application must recover.
+- Which capabilities remain unsupported.
+
+## Rails Result Delivery
+
+Register a host callback to receive each eligible job's sanitized `Result` after
+execution and cleanup:
+
+```ruby
+RubyLLM::Browser::Rails.result_delivery = lambda do |operation:, result:|
+  BrowserResults.persist(operation: operation, payload: result.to_h)
+end
+```
+
+Your application supplies `BrowserResults`, storage, access checks, retention, and
+idempotent recovery. The gem adds no database tables or runtime dependencies. Read
+[Rails Result Delivery]({% link _advanced/result-delivery.md %}) for the contract.
+
+Run `bundle exec ruby examples/rails_results.rb` for a disposable SQLite host example.
+It executes a serialized job in a separate process, waits for the worker to exit,
+then verifies result retrieval, actor/run isolation, and idempotent persistence.
+
+## Delivery Failure Is Separate from Cleanup
+
+A callback failure raises `Rails::ResultDeliveryError` with the retained operation and
+result. It does not change session state. A duplicate browser job does not rerun the
+operation or redeliver the result. Recover host delivery using the retained result;
+do not enqueue a new browser operation to recover persistence.
+
+The hook cannot guarantee delivery across worker crashes. Stagehand and live Act remain
+unsupported. Review [the roadmap]({% link _reference/roadmap.md %}) for live-backend
+qualification and the remaining 1.0 requirements.

data/docs/_reference/api-and-configuration.md

@@ -95,6 +95,10 @@ or redacted field need not retain the original schema's type. Always check the s
 
 ## Results and errors
 
+`Result` copies and freezes its strings and nested data. This includes operation ID,
+error code and error message; changes to constructor inputs cannot alter a retained
+result. Duplicate a returned string if host code needs to edit it.
+
 `Result#to_h` contains symbol keys: `status`, `operation_id`, `final_url`,
 `captured_at` (UTC ISO 8601), `locator`, `digest`, `truncated`, `data`, and optional
 `error: { code:, message: }`. Locator/data objects use string keys. JSON encodes all
@@ -182,6 +186,17 @@ is deferred to a later version. The Engine refuses all non-fake Act calls before
 a session. Selector/description keyword filters are defense in depth, not semantic proof
 that a click is harmless. The Stagehand adapter does not support Act in this release.
 
+## Rails Result Delivery
+
+After `require "ruby_llm/browser/rails"`, set `Rails.result_delivery` to a callable
+accepting `operation:` and `result:`, or `nil` to disable it. `Rails.reset!` clears the
+hook. The callback runs synchronously after execution and cleanup. Return values are
+ignored; exceptions become `Rails::ResultDeliveryError` (`RESULT_DELIVERY_FAILED`),
+which exposes `operation` and `result` to trusted recovery code. These objects are
+not automatically persisted. Duplicate browser jobs do not retry delivery. Read
+[Rails Result Delivery]({% link _advanced/result-delivery.md %}) for storage, access,
+cancellation, and crash boundaries.
+
 ## Next steps
 
 - Read [Rails integration]({% link _advanced/rails-integration.md %}) for durable workers and recovery.

data/docs/_reference/release-history.md

@@ -18,7 +18,8 @@ release notes to identify the exact source for this version.
 
 | Release | Date | Highlights |
 | --- | --- | --- |
-| [0.2.0]({% link _getting_started/whats-new-in-0-2.md %}) | 2026-10-19 | Read-only tool factory, backend-aware Doctor, and agent development/browser verification |
+| [0.3.0]({% link _getting_started/whats-new-in-0-3.md %}) | 2026-10-19 | Opt-in Rails result delivery, durable host example, recovery and upgrade verification |
+| [0.2.0]({% link _reference/whats-new-in-0-2.md %}) | 2026-10-19 | Read-only tool factory, backend-aware Doctor, and agent development/browser verification |
 | [0.1.0](https://github.com/yorzi/ruby_llm-browser/releases/tag/v0.1.0) | 2026-10-18 | Offline read-only Inspect and Extract, Rails adapter, and Act simulation; live Stagehand and live Act are unsupported |
 
 For changes to existing applications, follow [Upgrading]({% link _reference/upgrading.md %}).

data/docs/_reference/roadmap.md

@@ -24,8 +24,9 @@ Ruby and through the optional Rails adapter.
 
 Version 0.1.0 introduced the offline foundation: Inspect, Extract, URL policy, bounded
 results, operation bookkeeping, Rails jobs, and Act simulation. It does not provide a
-supported live backend. The current Stagehand adapter refuses live operations. Rails
-jobs track state but do not durably deliver result bodies.
+supported live backend. The current Stagehand adapter refuses live operations. The
+0.3.0 release adds opt-in Rails result delivery to host-owned storage;
+it does not add a gem-managed results database or guaranteed delivery.
 
 **This is a proposed development sequence, not a list of available features or release
 dates.** Future API names below are proposals. Keep each release small; use patch
@@ -48,8 +49,8 @@ feedback to settle the public API.
 
 ### 0.2.0: Two Small Features
 
-Version `0.2.0` adds both features below. Later milestones remain proposed scope. See
-[What's New]({% link _getting_started/whats-new-in-0-2.md %}) for usage and
+Version `0.2.0` adds both features below. Milestones after 0.3 remain proposed scope. See
+[What's New]({% link _reference/whats-new-in-0-2.md %}) for usage and
 [development and testing]({% link _advanced/development-and-testing.md %}) for validation.
 
 1. Add the read-only tool factory `RubyLLM::Browser.tools(context:, schema:)`.
@@ -72,8 +73,15 @@ validation precede the release tag and publication.
 
 ### 0.3.0: Complete the Rails Result Path
 
-Add an opt-in result-delivery hook that lets the host persist the sanitized `Result`
-against its operation ID. Provide a runnable host example that stores and retrieves
+Version `0.3.0` implements `Rails.result_delivery`, typed
+host-delivery failures, and a runnable SQLite host example with separate workers.
+Read [What's New in 0.3]({% link _getting_started/whats-new-in-0-3.md %}) and
+[Rails Result Delivery]({% link _advanced/result-delivery.md %}) for the current API.
+The source repository's `docs/evidence/V0_3_VALIDATION.md` records local candidate
+checks. `docs/evidence/V0_3_RELEASE.md` records remote verification and publication.
+
+The result-delivery hook lets the host persist the sanitized `Result`
+against its operation ID. Its runnable host example stores and retrieves
 the result after an asynchronous job finishes. The host owns access checks, retention,
 and storage; the gem does not need an admin interface or a general results database.
 

data/docs/_reference/upgrading.md

@@ -2,7 +2,7 @@
 layout: default
 title: Upgrading
 nav_order: 2
-description: Upgrade from 0.1.0 while preserving tool registration, diagnostics, and operation data.
+description: Upgrade from 0.2.0 while preserving operation data and configuring optional Rails result delivery.
 ---
 
 # {{ page.title }}
@@ -11,11 +11,11 @@ description: Upgrade from 0.1.0 while preserving tool registration, diagnostics,
 
 After reading this guide, you will know:
 
-- How to update an application from 0.1.0.
-- Which tool and diagnostic contracts remain compatible.
-- How to preserve data from earlier development snapshots.
+- How to update an application from 0.2.0.
+- How to preserve existing data and enable result delivery.
+- Which result and worker behaviors change.
 
-## Upgrade from 0.1.0
+## Upgrade from 0.2.0
 
 Update your Gemfile and bundle:
 
@@ -27,38 +27,41 @@ gem "ruby_llm-browser", "~> {{ site.version }}"
 bundle update ruby_llm-browser
 ```
 
-There is no database migration or new runtime dependency. Keep existing operation and
-approval records. The individual Inspect and Extract constructors remain supported.
-You can optionally replace their registration with:
+This release adds no gem-managed database migration or runtime dependency. Preserve all
+operation, approval, and actor-lock rows. Do not rerun the install generator on an
+existing installation. Result storage belongs to your application.
 
-```ruby
-chat.with_tools(*RubyLLM::Browser.tools(context: context, schema: schema))
-```
+## Enable Result Delivery When Needed
 
-The host still supplies the context and extraction schema. The factory never adds Act.
+`RubyLLM::Browser::Rails.result_delivery` defaults to `nil`. Existing job return values
+remain supported. To retain results after a worker exits, follow
+[Rails Result Delivery]({% link _advanced/result-delivery.md %}). Configure persistence,
+authorized reads, idempotent writes, and recovery before enabling the callback.
 
-## Read Doctor Reports by Name
+A callback failure raises `Rails::ResultDeliveryError`. Queue retries do not redeliver
+a result. The error retains the result only in process; it is not durable storage.
+Recover delivery separately from browser execution. A crash before host persistence
+can still lose the result, so do not treat this hook as guaranteed delivery.
 
-Doctor adds `mode` while retaining `ok`, `summary`, and `checks`. Check names now depend
-on the backend. Do not require Stagehand or credential checks in every report, and do
-not rely on check order. FakeBackend diagnostics skip provider environment and SDK
-checks. Stagehand still reports a failure; `mode: :live` does not enable it.
+## Account for Immutable Results and Fenced Workers
 
-Read [Checking Configuration]({% link _core_features/diagnostics.md %}) for the report
-fields. No live browser provider is supported by this release.
+`Result` now also copies and freezes operation ID, error code and error message strings,
+consistent with its other fields. Mutating these attributes raises `FrozenError`;
+duplicate a string before changing it in host code. Caller-owned inputs stay mutable.
 
-## Earlier Development Snapshots
+A worker fenced during browser execution now returns `:fenced_out` and cannot deliver
+its stale result. Cancelled work never invokes the delivery hook, including while
+cleanup remains pending. Delivery failures do not change the session state or free
+quota. Stagehand and live Act remain unsupported.
 
-If you used an earlier development Rails generator, preserve operation data and follow
-the additive migration instructions in the
-[Rails guide]({% link _advanced/rails-integration.md %}). Drain workers during migration;
-do not reuse idempotency keys for legacy rows without request digests.
+## Earlier Versions
 
-For the previous version's instructions, read the
-[0.1.0 upgrading guide](https://github.com/yorzi/ruby_llm-browser/blob/v0.1.0/docs/_reference/upgrading.md).
+For upgrades from 0.1.0 and earlier development snapshots, first follow the
+[0.2.0 upgrading guide](https://github.com/yorzi/ruby_llm-browser/blob/v0.2.0/docs/_reference/upgrading.md).
+Preserve operation data and use additive migrations where required.
 
 ## Next Steps
 
-- Read [What's New in 0.2]({% link _getting_started/whats-new-in-0-2.md %}).
+- Read [What's New in 0.3]({% link _getting_started/whats-new-in-0-3.md %}).
 - Review [release history]({% link _reference/release-history.md %}) and
   [live-backend qualification]({% link _advanced/live-backend-qualification.md %}).

data/docs/{_getting_started → _reference}/whats-new-in-0-2.md

@@ -1,9 +1,8 @@
 ---
 layout: default
 title: What's New in 0.2
-redirect_from:
-  - /whats-new/
-nav_order: 4
+parent: Release History
+nav_order: 1
 description: Use the read-only tool factory and backend-aware diagnostics in this release.
 ---
 

data/examples/rails_results.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+# A host-owned result table and a single-job file queue, using only FakeBackend.
+# This disposable demonstration is not a production queue, controller or migration.
+require "ruby_llm/browser/rails"
+require "logger"
+require "open3"
+require "tmpdir"
+
+module BrowserResultsExample
+  SCHEMA = { "type" => "object", "properties" => { "title" => { "type" => "string" } },
+             "required" => [ "title" ], "additionalProperties" => false }.freeze
+  RESOLVER = Object.new
+  def RESOLVER.getaddresses(_host) = [ "93.184.216.34" ]
+
+  class ResultRecord < ActiveRecord::Base
+    self.table_name = "example_browser_results"
+    self.primary_key = "operation_id"
+  end
+
+  class FileQueue
+    def initialize(path) = @path = path
+    def enqueue(job) = File.write(@path, JSON.generate(job.serialize))
+    def enqueue_at(*) = raise(ArgumentError, "demo queue supports immediate jobs only")
+  end
+
+  module_function
+
+  def connect(database)
+    ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: database, timeout: 5000)
+    ActiveRecord::Base.logger = Logger.new(IO::NULL)
+    ActiveJob::Base.logger = Logger.new(IO::NULL)
+    RubyLLM::Browser::Rails::Schema.create!
+    connection = ActiveRecord::Base.connection
+    return if connection.table_exists?(ResultRecord.table_name)
+
+    connection.create_table(ResultRecord.table_name, id: false) do |table|
+      table.string :operation_id, primary_key: true, null: false
+      table.string :actor_id, null: false
+      table.string :run_id, null: false
+      table.text :body, null: false
+      table.datetime :created_at, null: false
+    end
+  end
+
+  def configure(backend: RubyLLM::Browser::FakeBackend.new)
+    RubyLLM::Browser::Rails.context_factory = lambda do |actor_id:, run_id:|
+      RubyLLM::Browser::Context.new(
+        actor_id: actor_id, run_id: run_id, backend: backend,
+        source_policy: RubyLLM::Browser::Policy.new(allowed_hosts: [ "docs.example.com" ], resolver: RESOLVER),
+        operation_store: RubyLLM::Browser::Rails.operation_store
+      )
+    end
+    RubyLLM::Browser::Rails.result_delivery = lambda do |operation:, result:|
+      store_result(operation: operation, payload: result.to_h)
+    end
+  end
+
+  # Trusted server API. The worker supplies identity, never a model or request body.
+  def store_result(operation:, payload:)
+    body = RubyLLM::Browser::Redactor.canonical_json(payload)
+    ResultRecord.transaction do
+      record = ResultRecord.create_or_find_by!(operation_id: operation.id) do |row|
+        row.actor_id = operation.actor_id
+        row.run_id = operation.run_id
+        row.body = body
+      end
+      unless [ record.actor_id, record.run_id, record.body ] == [ operation.actor_id, operation.run_id, body ]
+        raise RubyLLM::Browser::InvalidInput, "conflicting result delivery"
+      end
+    end
+  end
+
+  # In an HTTP host, derive actor/run from authenticated records and recheck access.
+  # Use the same response for a missing result and an inaccessible result.
+  def read_result(operation_id:, actor_id:, run_id:)
+    record = ResultRecord.find_by(operation_id: operation_id, actor_id: actor_id, run_id: run_id)
+    raise RubyLLM::Browser::NotAuthorized, "result unavailable" unless record
+
+    JSON.parse(record.body)
+  end
+
+  def worker(database, queue_file)
+    connect(database)
+    backend = RubyLLM::Browser::FakeBackend.new
+    configure(backend: backend)
+    ActiveJob::Base.execute(JSON.parse(File.read(queue_file)))
+    puts JSON.generate(starts: backend.call_count(:start), closes: backend.call_count(:end_session))
+  end
+
+  def run_demo
+    Dir.mktmpdir("browser-results-") do |directory|
+      database = File.join(directory, "host.sqlite3")
+      queue_file = File.join(directory, "job.json")
+      connect(database)
+      ActiveJob::Base.queue_adapter = FileQueue.new(queue_file)
+      operation = RubyLLM::Browser::Rails::OperationJob.enqueue(
+        actor_id: "demo-actor", run_id: "demo-run", kind: :extract,
+        url: "https://docs.example.com/", schema: SCHEMA,
+        budget: RubyLLM::Browser::Budget.new, idempotency_key: "demo-result"
+      )
+      # capture3 waits for exit. Execute the serialized job twice in separate workers.
+      [ 1, 0 ].each do |expected_starts|
+        stdout, stderr, status = Open3.capture3(RbConfig.ruby, "-I", File.expand_path("../lib", __dir__),
+                                               __FILE__, "worker", database, queue_file)
+        raise "worker failed: #{stderr}" unless status.success?
+        unless JSON.parse(stdout) == { "starts" => expected_starts, "closes" => expected_starts }
+          raise "unexpected browser dispatch"
+        end
+      end
+
+      payload = read_result(operation_id: operation.id, actor_id: "demo-actor", run_id: "demo-run")
+      raise "lost extraction" unless payload.fetch("data") == { "title" => "Example" } && payload.fetch("status") == "ok"
+      raise "lost provenance" unless payload.fetch("locator").fetch("schema_digest") == RubyLLM::Browser::Redactor.digest(SCHEMA)
+      puts "RESULT_AFTER_WORKER_EXIT_PASS"
+
+      [ [ "other-actor", "demo-run" ], [ "demo-actor", "other-run" ] ].each do |actor, run|
+        begin
+          read_result(operation_id: operation.id, actor_id: actor, run_id: run)
+          raise "cross-scope result leak"
+        rescue RubyLLM::Browser::NotAuthorized
+          # Expected refusal, including after the worker has exited.
+        end
+      end
+      puts "SCOPED_READS_PASS"
+      2.times { store_result(operation: operation, payload: payload) }
+      raise "duplicate result rows" unless ResultRecord.count == 1
+      puts "IDEMPOTENT_WRITE_PASS"
+    ensure
+      ActiveRecord::Base.connection_pool.disconnect!
+    end
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  if ARGV.first == "worker"
+    BrowserResultsExample.worker(*ARGV.drop(1))
+  else
+    BrowserResultsExample.run_demo
+  end
+end

data/lib/ruby_llm/browser/rails/operation_job.rb

@@ -91,8 +91,14 @@ module RubyLLM
                                      max_bytes: max_bytes)
 
           # Keep unknown action/start results, even when cleanup later closes a session.
-          final = settled(operation_id)
+          completed = store.fetch!(operation_id)
+          final = settled(completed)
           return :cancelled if final == :cancelled
+          # Cancellation can still await cleanup. A reaper or newer worker can also
+          # fence this job while the browser call is in flight.
+          return :fenced_out unless completed.cancel_requested? || completed.fence == leased.fence
+
+          deliver(completed, result) unless completed.cancel_requested?
 
           result.ok? ? (final || result.to_h) : result.to_h
         rescue InvalidInput => e
@@ -106,15 +112,21 @@ module RubyLLM
         # Reports the durable state if the host cancelled or another worker fenced this
         # one while the operation was running; otherwise returns nil so the engine's own
         # result is used.
-        def settled(operation_id)
-          final = store.fetch(operation_id)
-          case final&.state
+        def settled(operation)
+          case operation.state
           when :cancelled then :cancelled
           when :cleanup_pending then :cleanup_pending
           when :unknown then :unknown
           end
         end
 
+        def deliver(operation, result)
+          RubyLLM::Browser::Rails.result_delivery&.call(operation: operation, result: result)
+        rescue StandardError
+          # Queue logs may print chained exceptions containing host credentials.
+          raise ResultDeliveryError.new(operation: operation, result: result), cause: nil
+        end
+
         def run(kind, operation, url:, instruction:, schema:, max_bytes:)
           context = build_context(operation)
           unless context.is_a?(Context) && context.operation_store.equal?(store)

data/lib/ruby_llm/browser/rails/result_delivery_error.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Browser
+    module Rails
+      # The host callback failed after browser execution and cleanup were attempted.
+      # Retain these values in host storage to retry delivery without rerunning a job.
+      # These are in-process objects, not a durable queue or automatic retry policy.
+      class ResultDeliveryError < Error
+        CODE = "RESULT_DELIVERY_FAILED"
+
+        attr_reader :operation, :result
+
+        def initialize(operation:, result:)
+          @operation = operation
+          @result = result
+          super("host result delivery failed; retry delivery without repeating browser work")
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/browser/rails.rb

@@ -27,6 +27,7 @@ require_relative "rails/operation_record"
 require_relative "rails/approval_record"
 require_relative "rails/active_record_operation_store"
 require_relative "rails/active_record_approval_store"
+require_relative "rails/result_delivery_error"
 require_relative "rails/operation_job"
 require_relative "rails/reaper"
 
@@ -41,6 +42,20 @@ module RubyLLM
         # ->(actor_id:, run_id:) { RubyLLM::Browser::Context }, supplied by the host.
         attr_accessor :context_factory
 
+        # Optional host callback: ->(operation:, result:) { persist_result }.
+        # Runs synchronously after execution and cleanup, before the job returns.
+        # Raise to report failure; return values are ignored. Duplicate jobs do not
+        # redeliver. The host owns persistence, idempotency, access and recovery.
+        attr_reader :result_delivery
+
+        def result_delivery=(callback)
+          unless callback.nil? || callback.respond_to?(:call)
+            raise InvalidInput, "result_delivery must be callable or nil"
+          end
+
+          @result_delivery = callback
+        end
+
         # Returns the current UTC time used by the adapter.
         def clock
           @clock ||= -> { Time.now.utc }
@@ -68,6 +83,7 @@ module RubyLLM
         # Restores process defaults. Primarily a test helper.
         def reset!
           @context_factory = nil
+          @result_delivery = nil
           @clock = nil
           @job_queue = nil
           @operation_store = nil

data/lib/ruby_llm/browser/result.rb

@@ -27,15 +27,15 @@ module RubyLLM
       def initialize(status:, operation_id: nil, final_url: nil, captured_at: nil, locator: nil,
                      digest: nil, data: nil, truncated: false, error_code: nil, error_message: nil)
         @status = normalize_status(status)
-        @operation_id = operation_id
+        @operation_id = Immutable.copy(operation_id)
         @final_url = Immutable.copy(final_url)
         @captured_at = Immutable.copy(captured_at)
         @locator = Immutable.copy(locator)
         @digest = Immutable.copy(digest)
         @data = Immutable.copy(data)
         @truncated = truncated ? true : false
-        @error_code = error_code
-        @error_message = error_message
+        @error_code = Immutable.copy(error_code)
+        @error_message = Immutable.copy(error_message)
         freeze
       end
 

data/lib/ruby_llm/browser/version.rb

@@ -4,6 +4,6 @@ module RubyLLM
   module Browser
     # The Gem version. Development happens ahead of any public release: the packaged
     # version is not a RubyGems publication claim.
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-browser
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Andy Wang
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-18 00:00:00.000000000 Z
+date: 2026-10-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -174,6 +174,7 @@ files:
 - docs/_advanced/development-and-testing.md
 - docs/_advanced/live-backend-qualification.md
 - docs/_advanced/rails-integration.md
+- docs/_advanced/result-delivery.md
 - docs/_config.yml
 - docs/_core_features/diagnostics.md
 - docs/_core_features/inspect-extract.md
@@ -186,13 +187,14 @@ files:
 - docs/_getting_started/configuration.md
 - docs/_getting_started/getting-started.md
 - docs/_getting_started/overview.md
-- docs/_getting_started/whats-new-in-0-2.md
+- docs/_getting_started/whats-new-in-0-3.md
 - docs/_plugins/versioned_docs.rb
 - docs/_reference/api-and-configuration.md
 - docs/_reference/api-reference.md
 - docs/_reference/release-history.md
 - docs/_reference/roadmap.md
 - docs/_reference/upgrading.md
+- docs/_reference/whats-new-in-0-2.md
 - docs/bin/build-api.sh
 - docs/bin/build.sh
 - docs/bin/export-api-markdown.rb
@@ -204,6 +206,7 @@ files:
 - docs/index.md
 - examples/plain_ruby.rb
 - examples/rails_adapter.rb
+- examples/rails_results.rb
 - lib/generators/ruby_llm/browser/install_generator.rb
 - lib/generators/ruby_llm/browser/templates/create_ruby_llm_browser_tables.rb.tt
 - lib/ruby_llm/browser.rb
@@ -232,6 +235,7 @@ files:
 - lib/ruby_llm/browser/rails/operation_job.rb
 - lib/ruby_llm/browser/rails/operation_record.rb
 - lib/ruby_llm/browser/rails/reaper.rb
+- lib/ruby_llm/browser/rails/result_delivery_error.rb
 - lib/ruby_llm/browser/rails/schema.rb
 - lib/ruby_llm/browser/redactor.rb
 - lib/ruby_llm/browser/result.rb