openui-rails 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d3b9295fd6e8fb6d3b284c0c66d80e3d02f01e7d1c09913f02acfd6ff183273
-  data.tar.gz: 9e5eb58014af64320ea178b05f63843f617f5fe3fa650e083f411a116a12dff2
+  metadata.gz: 9a8e938067e723b80e9efc974e2a2bd19878499bdc459c6d675452fa919584fb
+  data.tar.gz: 1a0d9ffaa09afef3c185f21154c56bf78ef8141f15bf4bef8fe1562aa47eb68b
 SHA512:
-  metadata.gz: bcbbc65b5a3a3d66839d727e325238643973050b39248695e6623b4f45c7fd343ecea7cf52c8c59f70fe6caf63aace284c677d4cd50211ed4fef73e9fc984da7
-  data.tar.gz: 53147d0d353adf39e448f3ea82ac1c60dd1f7fee9168573d5802b052a3bd54fbd949fd9ac5b8d591ff134cc627c9204feeb07ffd1289304109b5eedd41ea08c0
+  metadata.gz: 0161351030bb99e07eb7fa9c7fa968c4921ea436e76da253c6b1827ac3a55650e0dfc6903d737cd1ae94a71b9ae978ae20642e9ea9aec5dd5aa0bd550ff5eb2c
+  data.tar.gz: 6b583705522c3871e981289572701a5c0c62bb6c9a8cb7679c26a6af9cac185937d4401b960c4a653442f08ef08b8b552468e42deeaf7ba45bcca5d78e491005

data/CHANGELOG.md

@@ -6,6 +6,43 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-10-21
+
+### Added
+
+- Content-free `action.openui_rails` and `stream.openui_rails` notifications with
+  monotonic duration, fixed outcomes, replay status, and stream watermarks.
+- Browser `openui:ready` and `openui:snapshot-applied` events for host-owned
+  fallback and recovery, plus stable runtime and network failure codes.
+- Ordinary HTML fallback and explicit reload, scoped snapshot, and fresh sign-in
+  controls in the reference host, with keyboard and Turbo restoration checks.
+
+### Fixed
+
+- Late action responses cannot report into a reconnected surface. Failed
+  runtime scripts are removed so later mounts can retry loading.
+- Unmounted renderer callbacks cannot send actions, tool requests, state, or
+  errors through a new connection. A late snapshot cannot dismiss a host's
+  authentication or permission failure.
+- Browser failures use events without automatically logging raw error objects.
+
+## [0.4.0] - 2026-10-20
+
+### Added
+
+- Optional `Actions::Idempotency::ActiveRecordStore` with atomic database claims,
+  ownership fencing, JSON result persistence, and explicit expiry cleanup.
+  SQLite is the verified database; memory remains the default.
+- `openui:idempotency` generates the opt-in table and its unique key and expiry
+  indexes. Installing the engine alone creates no shared-store table.
+- Reusable Minitest store-conformance checks, independent-process SQLite tests,
+  and a fresh-host migration and restart check against the built gem.
+
+### Changed
+
+- The support-desk reference uses the shared store while retaining its business
+  uniqueness constraint. A shared claim does not guarantee exactly-once effects.
+
 ## [0.3.0] - 2026-10-19
 
 ### Added
@@ -116,7 +153,9 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - Gem-scoped RubyGems Trusted Publishing through GitHub OIDC, with a protected
   release environment and verified artifact handoff.
 
-[Unreleased]: https://github.com/yorzi/openui-rails/compare/v0.3.0...main
+[Unreleased]: https://github.com/yorzi/openui-rails/compare/v0.5.0...main
+[0.5.0]: https://github.com/yorzi/openui-rails/releases/tag/v0.5.0
+[0.4.0]: https://github.com/yorzi/openui-rails/releases/tag/v0.4.0
 [0.3.0]: https://github.com/yorzi/openui-rails/releases/tag/v0.3.0
 [0.2.0]: https://github.com/yorzi/openui-rails/releases/tag/v0.2.0
 [0.1.0]: https://github.com/yorzi/openui-rails/releases/tag/v0.1.0

data/CONTRIBUTING.md

@@ -25,7 +25,7 @@ bundle exec bin/rails test        # unit + integration tests
 bundle exec bin/rails test:system # browser (system) tests, needs Chrome
 bundle exec rubocop               # style (rubocop-rails-omakase)
 bundle exec gem build openui-rails.gemspec
-bundle exec ruby bin/smoke-package openui-rails-0.3.0.gem
+bundle exec ruby bin/smoke-package openui-rails-0.5.0.gem
 bundle exec bundler-audit check --update
 bundle exec ruby -Itest test/compatibility/ruby_llm_smoke.rb
 ```

data/DEVELOPMENT.md

@@ -17,7 +17,7 @@ authorizes a live call. Follow this loop for each feature:
 ```sh
 bin/check-reference
 bin/check-reference --runtime tmp/real-runtime
-bin/check-reference --gem tmp/package/openui-rails-0.3.0.gem --runtime tmp/real-runtime
+bin/check-reference --gem tmp/package/openui-rails-0.5.0.gem --runtime tmp/real-runtime
 # Focus one browser scenario:
 bin/check-reference --runtime tmp/real-runtime --name test_a_lost_turbo_envelope_recovers_from_the_scoped_snapshot
 ```

data/README.md

@@ -22,8 +22,8 @@ or renderer.
 - One allowlisted action endpoint with authorization, validation, and replay protection.
 - An optional RubyLLM streaming adapter.
 
-Your app supplies scoped record lookup, stream subscriptions, snapshot recovery,
-and shared idempotency storage when running multiple processes.
+Your app supplies scoped record lookup, stream subscriptions, and snapshot
+recovery. Multi-process apps can opt into the SQLite shared idempotency store.
 
 ## Get started
 
@@ -32,7 +32,7 @@ The runtime-fetch task also needs npm. RubyLLM is optional.
 
 ```ruby
 # Gemfile
-gem "openui-rails", "~> 0.3.0"
+gem "openui-rails", "~> 0.5.0"
 ```
 
 ```sh
@@ -65,15 +65,15 @@ The documentation site contains the full guides and API reference:
 - [RubyLLM](https://openui-rails.wangyaodi.com/ruby-llm/) and [production setup](https://openui-rails.wangyaodi.com/production/)
 - [Upgrading](https://openui-rails.wangyaodi.com/upgrading/) and [API reference](https://openui-rails.wangyaodi.com/api-reference/)
 
-Version `0.3.0` adds a persisted reference workflow and stream restoration.
-See [What's New](https://openui-rails.wangyaodi.com/whats-new-in-0-3/) for the upgrade.
+Version `0.5.0` adds outcome diagnostics and host-owned recovery examples.
+See [What's New](https://openui-rails.wangyaodi.com/whats-new-in-0-5/) for the upgrade.
 The API may change during `0.x`; see the
 [changelog](CHANGELOG.md) and the proposed [path to 1.0](ROADMAP.md).
 The site's stable channel follows the latest release; [/next/](https://openui-rails.wangyaodi.com/next/)
 follows `main`.
 
 For repository work, use [Contributing](CONTRIBUTING.md),
-[Releasing](RELEASING.md), and the [0.2.0 release record](RELEASE_0_2.md).
+[Releasing](RELEASING.md), and the [0.4.0 release record](RELEASE_0_4.md).
 Report vulnerabilities through the [security policy](SECURITY.md).
 
 ## License

data/app/controllers/openui/rails/actions_controller.rb

@@ -54,14 +54,7 @@ module OpenUI
       end
 
       def error_code(error)
-        case error
-        when UnknownActionError then "unknown_action"
-        when UnauthorizedActionError then "unauthorized"
-        when StaleSurfaceError then "stale_surface"
-        when ReplayError then "replay"
-        when InvalidActionError then "invalid_action"
-        else "error"
-        end
+        Instrumentation.action_error_code(error)
       end
 
       def error_status(error)

data/app/javascript/openui/rails/openui_controller.js

@@ -12,16 +12,18 @@ function loadRuntime(url, integrity) {
       script.async = true
       script.crossOrigin = "anonymous"
       if (integrity) script.integrity = integrity
+      const failed = (message) => {
+        script.remove()
+        reject(Object.assign(new Error(message), { code: "runtime_load_failed" }))
+      }
       script.addEventListener("load", () => {
         if (!window.__OpenUI) {
-          reject(new Error(`OpenUI runtime at ${url} did not expose window.__OpenUI`))
+          failed("OpenUI runtime did not expose window.__OpenUI")
           return
         }
         resolve(window.__OpenUI)
       })
-      script.addEventListener("error", () =>
-        reject(new Error(`Failed to load the OpenUI runtime from ${url}`))
-      )
+      script.addEventListener("error", () => failed("Failed to load the OpenUI runtime"))
       document.head.appendChild(script)
     })
     promise.catch(() => runtimePromises.delete(url))
@@ -80,6 +82,8 @@ export default class extends Controller {
     this.abortController?.abort()
     this.root?.unmount()
     this.root = null
+    this.runtime = null
+    this.tools = null
     this.mountPoint?.remove()
     this.mountPoint = null
   }
@@ -88,11 +92,11 @@ export default class extends Controller {
     try {
       const runtime = await loadRuntime(this.runtimeUrl, this.runtimeIntegrity)
       await this.verifyLibrary(runtime.openuiChatLibrary)
-      if (connection !== this.connection || !this.element.isConnected || !this.mountPoint) return
+      if (!this.isCurrent(connection) || !this.mountPoint) return
       this.runtime = runtime
-      this.render()
+      if (this.render()) this.dispatch("ready", { surfaceId: this.surfaceId })
     } catch (error) {
-      if (connection !== this.connection) return
+      if (!this.isCurrent(connection)) return
       this.state.streaming = false
       this.syncBusy()
       this.handleError(error)
@@ -104,6 +108,7 @@ export default class extends Controller {
     if (!this.runtime || !this.mountPoint || !this.connection) return
     if (!this.withinByteLimit(this.state.source)) return
     const { React, createRoot, Renderer, openuiChatLibrary } = this.runtime
+    const connection = this.connection
     if (!this.root) this.root = createRoot(this.mountPoint)
     this.root.render(
       React.createElement(Renderer, {
@@ -115,12 +120,13 @@ export default class extends Controller {
         initialState: this.initialState,
         // The official runtime emits { type, params }. It does not await this
         // void callback; dispatchAction already emits a structured error.
-        onAction: (action) => { this.dispatchAction(action).catch(() => {}) },
-        onStateUpdate: (formState) => this.persistState(formState),
+        onAction: (action) => { if (this.isCurrent(connection)) this.dispatchAction(action).catch(() => {}) },
+        onStateUpdate: (formState) => { if (this.isCurrent(connection)) this.persistState(formState) },
         toolProvider: this.toolProvider(),
-        onError: (error) => this.handleError(error),
+        onError: (error) => { if (this.isCurrent(connection)) this.handleError(error) },
       })
     )
+    return true
   }
 
   async verifyLibrary(library) {
@@ -203,6 +209,7 @@ export default class extends Controller {
     this.state.streaming = envelope.streaming === true
     this.state.completed = !this.state.streaming
     this.render()
+    this.dispatch("snapshot-applied", { surfaceId: this.surfaceId, sequence: envelope.sequence })
   }
 
   requestSnapshot() {
@@ -224,6 +231,8 @@ export default class extends Controller {
   // --- Actions -------------------------------------------------------------
 
   async dispatchAction(payload = {}) {
+    const connection = this.connection
+    if (!this.isCurrent(connection)) throw new DOMException("Surface disconnected", "AbortError")
     const body = {
       action: payload.action ?? payload.name ?? payload.type,
       args: this.actionArguments(payload),
@@ -241,6 +250,7 @@ export default class extends Controller {
         headers: this.headers(),
         body: JSON.stringify(body),
       })
+      if (!this.isCurrent(connection)) throw new DOMException("Surface disconnected", "AbortError")
       if (response.redirected) {
         throw Object.assign(new Error("Action request was redirected; authentication may have expired"), { code: "unauthorized" })
       }
@@ -253,8 +263,9 @@ export default class extends Controller {
       } catch {
         throw Object.assign(new Error("Action endpoint returned malformed JSON"), { code: "invalid_response" })
       }
+      if (!this.isCurrent(connection)) throw new DOMException("Surface disconnected", "AbortError")
       if (!response.ok) {
-        throw Object.assign(new Error(json?.error?.message || "action failed"), { code: json?.error?.code })
+        throw Object.assign(new Error(json?.error?.message || "action failed"), { code: json?.error?.code || "action_failed" })
       }
       const result = json?.result
       if (!result || result.action !== body.action || result.surface_id !== body.surface_id || result.version !== body.version) {
@@ -263,7 +274,7 @@ export default class extends Controller {
       this.dispatch("action", { surfaceId: this.surfaceId, result })
       return result
     } catch (error) {
-      if (error.name !== "AbortError" || this.connection) this.handleError(error)
+      if (this.isCurrent(connection)) this.handleError(error, error.name === "AbortError" ? "request_cancelled" : "network_error")
       throw error
     }
   }
@@ -284,6 +295,7 @@ export default class extends Controller {
   // Every browser `Query()`/`Mutation()` tool call is routed to the same
   // server endpoint; the host registry decides what is permitted.
   toolProvider() {
+    const connection = this.connection
     const reserved = new Set([ "callTool", "then", "__proto__", "constructor", "prototype", "toJSON" ])
     return this.tools ||= new Proxy(
       {},
@@ -291,7 +303,10 @@ export default class extends Controller {
         has: (_target, name) => typeof name === "string" && !reserved.has(name),
         get: (_target, name) => {
           if (typeof name !== "string" || reserved.has(name)) return undefined
-          return (args) => this.dispatchAction({ action: name, args: args ?? {} }).then((result) => result.value)
+          return (args) => {
+            if (!this.isCurrent(connection)) return Promise.reject(new DOMException("Surface disconnected", "AbortError"))
+            return this.dispatchAction({ action: name, args: args ?? {} }).then((result) => result.value)
+          }
         },
       }
     )
@@ -310,17 +325,19 @@ export default class extends Controller {
     this.element.setAttribute("aria-busy", this.state.streaming ? "true" : "false")
   }
 
-  handleError(error) {
+  handleError(error, fallbackCode = "renderer_error") {
     // Renderer#onError receives an array, including [] after successful parses.
     if (Array.isArray(error)) {
       if (error.length === 0) return
       error = Object.assign(new Error(error.map((entry) => entry.message || String(entry)).join("; ")),
         { code: "renderer_error" })
     }
-    console.error("[openui-rails]", error)
-    this.dispatch("error", { surfaceId: this.surfaceId, message: error?.message, code: error?.code })
+    this.dispatch("error", { surfaceId: this.surfaceId, message: error?.message,
+      code: typeof error?.code === "string" ? error.code : fallbackCode })
   }
 
+  isCurrent(connection) { return !!connection && connection === this.connection && this.element.isConnected }
+
   headers() {
     const token = document.querySelector("meta[name='csrf-token']")?.content
     const headers = { "Content-Type": "application/json", Accept: "application/json" }

data/examples/support_desk/README.md

@@ -2,14 +2,21 @@
 
 This opt-in reference belongs to the host application, outside the engine's
 public API. It uses synthetic accounts, recorded generation, the real pinned
-OpenUI runtime, SQLite, importmap, and HTTP Turbo Streams.
+OpenUI runtime, SQLite, importmap, and HTTP Turbo Streams. It opts into the
+Active Record idempotency store and retains a unique business receipt for closing
+a ticket. Shared claims do not replace that database constraint.
+
+The plain HTML fallback provides ticket details, an explicit reload, and a fresh
+sign-in. Snapshot recovery is scoped and single-flight. Unknown action outcomes
+are never retried automatically. Browser checks cover failure feedback, keyboard
+recovery, and Turbo restoration as well as the successful workflow.
 
 From the repository:
 
 ```sh
 mkdir -p tmp/package
-bundle exec gem build openui-rails.gemspec --output tmp/package/openui-rails-0.3.0.gem
-bin/check-reference --gem tmp/package/openui-rails-0.3.0.gem --runtime tmp/real-runtime
+bundle exec gem build openui-rails.gemspec --output tmp/package/openui-rails-0.5.0.gem
+bin/check-reference --gem tmp/package/openui-rails-0.5.0.gem --runtime tmp/real-runtime
 ```
 
 Fetch the runtime first. See the [complete guide](https://openui-rails.wangyaodi.com/reference-workflow/)

data/examples/support_desk/app/javascript/support_desk.js

@@ -5,37 +5,68 @@ import EnvelopeController from "openui/rails/openui_envelope_controller"
 
 class SupportDeskController extends Controller {
   connect() {
+    this.connection = Symbol("support-desk")
     this.abort = new AbortController()
     this.saves = Promise.resolve()
     this.lastState = null
-    if (this.surface.dataset.openuiStreaming === "true") this.stream().catch(error => this.failure(error))
+    this.runtimeReady = false
+    this.recovering = false
+    this.failureCode = this.element.dataset.supportDeskFailure || null
+    this.beforeCache = () => this.disconnect()
+    document.addEventListener("turbo:before-cache", this.beforeCache)
+    if (this.surface.dataset.openuiStreaming === "true" && !this.failureCode) {
+      const connection = this.connection
+      this.stream(connection).catch(error => { if (this.current(connection)) this.failure(error) })
+    }
   }
 
-  disconnect() { this.abort.abort() }
+  disconnect() {
+    this.connection = null
+    this.abort?.abort()
+    document.removeEventListener("turbo:before-cache", this.beforeCache)
+  }
+  current(connection) { return !!connection && connection === this.connection && this.element.isConnected }
   get surface() { return this.element.querySelector("[data-controller='openui']") }
   get status() { return this.element.querySelector("#desk-status") }
+  get fallback() { return this.element.querySelector("#desk-fallback") }
+  get recoverButton() { return this.element.querySelector("#desk-recover") }
 
   headers() {
     return { "Content-Type": "application/json", "X-CSRF-Token": document.querySelector("meta[name='csrf-token']").content }
   }
 
-  async checked(response) {
-    if (response.redirected || !response.ok) throw new Error(response.status === 401 || response.status === 403 ? "Session expired. Sign in again." : "Request rejected. Reload the conversation.")
+  checked(response) {
+    if (response.redirected || [401, 403].includes(response.status)) {
+      throw Object.assign(new Error("Session or permission rejected"), { code: "unauthorized" })
+    }
+    if (!response.ok) throw Object.assign(new Error("Request rejected"), {
+      code: response.status === 409 ? "stale_surface" : "request_failed"
+    })
     return response
   }
 
-  // Consume newline-delimited Turbo Stream elements as response chunks arrive.
-  // Authorization and canonical response persistence happen before delivery.
-  async stream() {
-    const response = await this.checked(await fetch(this.element.dataset.supportDeskStreamUrl, {
+  ready() {
+    this.runtimeReady = true
+    if (!this.failureCode) {
+      this.fallback.hidden = true
+      this.surface.inert = false
+    }
+  }
+
+  // Persisted canonical output is independent of this disposable connection.
+  async stream(connection) {
+    const response = await fetch(this.element.dataset.supportDeskStreamUrl, {
       method: "POST", headers: this.headers(), signal: this.abort.signal, credentials: "same-origin"
-    }))
+    })
+    if (!this.current(connection)) return
+    this.checked(response)
     const reader = response.body.getReader()
     const decoder = new TextDecoder()
     let pending = ""
     try {
       while (true) {
         const { value, done } = await reader.read()
+        if (!this.current(connection)) return
         pending += decoder.decode(value, { stream: !done })
         let end
         while ((end = pending.indexOf("\n")) >= 0) {
@@ -44,26 +75,54 @@ class SupportDeskController extends Controller {
         }
         if (done) break
       }
-      if (pending.trim()) throw new Error("Incomplete stream. Reload the conversation.")
-      this.status.textContent = "Response loaded"
+      if (pending.trim()) throw new Error("Incomplete stream")
+      if (!this.failureCode) this.status.textContent = "Response loaded"
     } finally {
       await reader.cancel().catch(() => {})
     }
   }
 
   async recover() {
-    if (this.recovering) return
+    if (!this.current(this.connection) || this.recovering || ["unauthorized", "csrf_failed"].includes(this.failureCode)) return
+    const connection = this.connection
     this.recovering = true
+    this.failure({ code: "sequence_gap" })
+    this.recoverButton.disabled = true
+    this.recoverButton.setAttribute("aria-busy", "true")
+    this.status.textContent = "Restoring saved response"
     try {
-      const response = await this.checked(await fetch(this.element.dataset.supportDeskSnapshotUrl, {
+      const response = await fetch(this.element.dataset.supportDeskSnapshotUrl, {
         headers: { Accept: "application/json" }, signal: this.abort.signal, credentials: "same-origin"
-      }))
-      const envelope = await response.json()
+      })
+      if (!this.current(connection)) return
+      const envelope = await this.checked(response).json()
+      if (!this.current(connection)) return
+      this.snapshotApplied = false
       this.surface.dispatchEvent(new CustomEvent("openui:envelope", { bubbles: true, detail: envelope }))
-      this.element.dataset.recovered = "true"
-      this.status.textContent = "Recovered from a missing update"
-    } catch (error) { this.failure(error) }
-    finally { this.recovering = false }
+      if (!this.snapshotApplied) throw Object.assign(new Error("Snapshot not accepted"), { code: "snapshot_unavailable" })
+    } catch (error) {
+      if (this.current(connection)) this.failure(error)
+    } finally {
+      if (this.current(connection)) {
+        this.recovering = false
+        this.recoverButton.disabled = this.failureCode !== "sequence_gap" && this.failureCode !== "request_failed"
+        this.recoverButton.setAttribute("aria-busy", "false")
+      }
+    }
+  }
+
+  restored() {
+    this.snapshotApplied = true
+    // A transport snapshot cannot restore identity or permission. Keep that
+    // failure visible until the host performs a fresh sign-in or reload.
+    if (this.failureCode && !["sequence_gap", "request_failed"].includes(this.failureCode)) return
+    this.failureCode = null
+    delete this.element.dataset.supportDeskFailure
+    this.element.dataset.recovered = "true"
+    this.element.querySelector("#desk-error").textContent = ""
+    this.status.textContent = "Recovered from a missing update"
+    this.surface.inert = false
+    if (this.runtimeReady) this.fallback.hidden = true
   }
 
   saveState(event) {
@@ -74,32 +133,58 @@ class SupportDeskController extends Controller {
     if (this.lastState === serialized) return
     this.lastState = serialized
     this.status.textContent = "Saving draft"
+    const connection = this.connection, signal = this.abort.signal
     const version = Number(this.surface.dataset.openuiVersion)
     this.saves = this.saves.then(async () => {
-      await this.checked(await fetch(this.element.dataset.supportDeskStateUrl, {
-        method: "PATCH", headers: this.headers(), credentials: "same-origin", signal: this.abort.signal,
+      if (!this.current(connection)) return
+      const response = await fetch(this.element.dataset.supportDeskStateUrl, {
+        method: "PATCH", headers: this.headers(), credentials: "same-origin", signal,
         body: JSON.stringify({ state, version })
-      }))
-      if (this.lastState === serialized) this.status.textContent = "Draft saved"
-    }).catch(error => this.failure(error))
+      })
+      if (!this.current(connection)) return
+      this.checked(response)
+      if (this.lastState === serialized && !this.failureCode) this.status.textContent = "Draft saved"
+    }).catch(error => { if (this.current(connection)) this.failure(error) })
   }
 
   async action(event) {
     if (!["continue_conversation", "close_ticket"].includes(event.detail.result.action)) return
+    const connection = this.connection
     await this.saves
-    window.location.reload()
+    if (this.current(connection)) window.location.reload()
   }
 
   error(event) {
-    if (["unauthorized", "csrf_failed"].includes(event.detail.code)) {
-      this.denied = true
-      this.failure(new Error("Action not permitted. Sign in again."))
-    } else if (!this.denied) {
-      this.failure(new Error(event.detail.message || "Unable to render this response."))
-    }
+    // The runtime can report a secondary parse failure after an action error.
+    // Keep the actionable server outcome instead of replacing it with that echo.
+    if (this.failureCode && event.detail.code === "renderer_error") return
+    this.failure(event.detail)
   }
+
   failure(error) {
-    if (error.name !== "AbortError") this.element.querySelector("#desk-error").textContent = error.message
+    if (error.name === "AbortError") return
+    this.failureCode = error.code || "request_failed"
+    this.element.dataset.supportDeskFailure = this.failureCode
+    const messages = {
+      runtime_load_failed: "Interactive view could not load. Review the ticket details or reload.",
+      library_version_mismatch: "The response uses a different library. Reload after correcting setup.",
+      provider_rejected: "Generation stopped. Reload the saved conversation before trying again.",
+      stream_failed: "Generation stopped. Reload the saved conversation before trying again.",
+      stream_cancelled: "Generation stopped. Reload the saved conversation before trying again.",
+      stream_too_large: "The response is too large. Reload the saved conversation.",
+      stale_surface: "Conversation changed. Reload before submitting another action.",
+      unauthorized: "Action not permitted. Sign in again.",
+      csrf_failed: "Action not permitted. Sign in again.",
+      sequence_gap: "An update is missing. Restore the saved response or reload.",
+      snapshot_unavailable: "Saved response cannot be applied. Reload the conversation.",
+      renderer_error: "Interactive response could not render. Reload the conversation."
+    }
+    this.element.querySelector("#desk-error").textContent = messages[this.failureCode] || "Request failed; its outcome may be unknown. Reload canonical state before trying again."
+    this.fallback.hidden = false
+    this.surface.inert = true
+    this.recoverButton.disabled = !["sequence_gap", "request_failed"].includes(this.failureCode)
+    this.element.querySelector("#desk-sign-in").hidden = !["unauthorized", "csrf_failed"].includes(this.failureCode)
+    this.status.textContent = "Recovery required"
   }
 }
 

data/examples/support_desk/app/views/support_desk/conversations/show.html.erb

@@ -1,6 +1,7 @@
 <header>
   <h1>Support Desk</h1>
   <span><%= current_actor.name %> · <%= current_actor.tenant_id %> tenant</span>
+  <%= link_to "Conversations", root_path %>
   <%= button_to "Sign out", session_path, method: :delete %>
 </header>
 <p class="notice">Recorded response, real OpenUI runtime. Your Rails host owns the ticket and conversation.</p>
@@ -8,9 +9,18 @@
          data-support-desk-stream-url="<%= stream_conversation_path(@conversation) %>"
          data-support-desk-snapshot-url="<%= snapshot_conversation_path(@conversation) %>"
          data-support-desk-state-url="<%= state_conversation_path(@conversation) %>"
-         data-action="openui:state->support-desk#saveState openui:snapshot-required->support-desk#recover openui:action->support-desk#action openui:error->support-desk#error">
+         data-action="openui:ready->support-desk#ready openui:snapshot-applied->support-desk#restored openui:state->support-desk#saveState openui:snapshot-required->support-desk#recover openui:action->support-desk#action openui:error->support-desk#error">
   <%= openui_surface(surface: @conversation.surface, label: "Support ticket") %>
   <div id="desk-envelopes" hidden></div>
   <p role="status" id="desk-status">Ready</p>
   <p role="alert" id="desk-error"></p>
+  <aside id="desk-fallback" class="notice" aria-labelledby="desk-fallback-title">
+    <h2 id="desk-fallback-title">Ticket details and recovery</h2>
+    <p><%= @conversation.ticket.title %> · <%= @conversation.ticket.status %></p>
+    <p>If the interactive view is unavailable, review these saved details. Reloading does not resubmit your last action.</p>
+    <%= link_to "Reload conversation", conversation_path(@conversation), data: { turbo: false } %>
+    <%= link_to "Sign in again", root_path, id: "desk-sign-in", data: { turbo: false }, hidden: true %>
+    <button id="desk-recover" type="button" disabled aria-busy="false" aria-describedby="desk-error"
+            data-action="support-desk#recover">Restore saved response</button>
+  </aside>
 </section>

data/examples/support_desk/config/initializers/openui.rb

@@ -8,6 +8,7 @@ OpenUI::Rails.configure do |config|
   config.surface_resolver = ->(id, actor:, **) {
     SupportDesk::Conversation.find_by(id: id, user_id: actor.id, tenant_id: actor.tenant_id) if actor
   }
+  config.idempotency_store = OpenUI::Rails::Actions::Idempotency::ActiveRecordStore.new
   config.idempotency_scope = ->(invocation) { [ invocation.actor.tenant_id, invocation.actor.id ] }
   config.authorize_action = ->(invocation) {
     actor, conversation = invocation.actor, invocation.surface

data/lib/generators/openui/idempotency/idempotency_generator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "rails/generators/active_record"
+
+module OpenUI
+  # Generate the opt-in shared action-claim table without changing configuration.
+  class IdempotencyGenerator < ::ActiveRecord::Generators::Base
+    namespace "openui:idempotency"
+    source_root File.expand_path("templates", __dir__)
+    desc "Create the optional OpenUI shared idempotency store migration."
+    # This generator has no model-name argument.
+    argument :name, type: :string, default: "openui_action_claims", hide: true
+
+    # Write the optional, reversible host migration.
+    def create_store_migration
+      migration_template "create_openui_action_claims.rb", "db/migrate/create_openui_action_claims.rb"
+    end
+  end
+end

data/lib/generators/openui/idempotency/templates/create_openui_action_claims.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class CreateOpenUIActionClaims < ActiveRecord::Migration[8.0]
+  def change
+    create_table :openui_action_claims do |t|
+      t.string :key, null: false
+      t.string :digest
+      t.string :claim_token, null: false
+      t.boolean :completed, null: false, default: false
+      t.text :result_json
+      t.datetime :expires_at, null: false, precision: 6
+    end
+    add_index :openui_action_claims, :key, unique: true
+    add_index :openui_action_claims, :expires_at
+  end
+end

data/lib/generators/openui/install/templates/config/initializers/openui.rb.tt

@@ -14,6 +14,10 @@ OpenUI::Rails.configure do |config|
   config.runtime_assets = :self_hosted
   # config.runtime_integrity = "sha384-..."
 
+  # Optional shared SQLite claims: first run openui:idempotency and db:migrate.
+  # See the Shared Idempotency Storage guide for JSON results and crash limits.
+  # config.idempotency_store = OpenUI::Rails::Actions::Idempotency::ActiveRecordStore.new
+
   # Authorize every action/tool call. This fails closed: with no authorizer an
   # action is denied. Return truthy to permit.
   # config.authorize_action = ->(invocation) do

data/lib/openui/rails/actions/dispatcher.rb

@@ -78,8 +78,16 @@ module OpenUI
         #
         # @return [Result]
         #
-        # @raise [OpenUI::Rails::Error] on any failed gate, before side effects
+        # Emits one content-free action.openui_rails outcome notification.
+        # Failed gates run before the handler. Handler and storage failures can
+        # occur after a business effect; hosts must reconcile that outcome.
+        #
+        # @raise [OpenUI::Rails::Error] on a failed gate or domain operation
         def call(payload, actor: nil, surface: nil, tenant: nil, context: {})
+          started = Instrumentation.now
+          outcome = "rejected"
+          replayed = false
+          code = nil
           submission = Submission.parse(payload)
           definition = @registry.fetch(submission.action)
 
@@ -102,11 +110,22 @@ module OpenUI
           authorize!(definition, invocation)
 
           replayed, stored, key, token = claim_idempotency(submission, invocation)
-          return result(submission, stored, replayed: true) if replayed
+          if replayed
+            outcome = "replayed"
+            return result(submission, stored, replayed: true)
+          end
 
+          outcome = "failed"
           value = definition.handler.call(invocation)
           @idempotency_store.record(key, value, claim_token: token)
+          outcome = "succeeded"
           result(submission, value, replayed: false)
+        rescue StandardError => error
+          code = Instrumentation.action_error_code(error)
+          outcome = "failed" unless error.is_a?(Error)
+          raise
+        ensure
+          Instrumentation.publish("action", started: started, outcome: outcome, code: code, replayed: replayed == true)
         end
 
         private

data/lib/openui/rails/actions/idempotency/active_record_store.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "active_record"
+require "json"
+require "securerandom"
+
+module OpenUI
+  module Rails
+    module Actions
+      module Idempotency
+        # Optional shared action store. Verified with SQLite on Rails 8.0/8.1.
+        # Install its table with `rails generate openui:idempotency` and db:migrate.
+        # JSON values replay across workers; object keys become strings. TTL runs
+        # from claim creation, not completion. Never assumes exactly-once effects.
+        class ActiveRecordStore
+          class Entry < ::ActiveRecord::Base # :nodoc:
+            self.table_name = "openui_action_claims"
+          end
+          private_constant :Entry
+
+          # @param model [Class] dedicated Active Record model, optionally using another database
+          # @param clock [#call] shared wall clock returning UTC Time values
+          def initialize(model: Entry, clock: -> { Time.now.utc })
+            @model = model
+            @clock = clock
+          end
+
+          # Atomically insert or replace an expired claim. Returns the same
+          # [status, result, stored_digest, token] contract as MemoryStore.
+          # A changed digest is returned to the dispatcher, which rejects it.
+          def claim(key, ttl:, digest: nil)
+            raise ConfigurationError, "idempotency ttl must be positive" unless ttl.is_a?(Numeric) && ttl.finite? && ttl > 0
+
+            loop do
+              now = @clock.call
+              attributes = { key: key, digest: digest, claim_token: SecureRandom.hex(16),
+                             completed: false, result_json: nil, expires_at: now + ttl }
+              inserted = @model.insert_all([ attributes ], unique_by: :key, returning: %w[id])
+              return [ :claimed, nil, digest, attributes[:claim_token] ] if inserted.any?
+
+              replaced = @model.where(key: key).where("expires_at <= ?", now).update_all(attributes.except(:key))
+              return [ :claimed, nil, digest, attributes[:claim_token] ] if replaced == 1
+
+              # Cleanup can delete the expired row between SQL statements.
+              entry = @model.find_by(key: key)
+              next unless entry
+
+              value = entry.completed ? JSON.parse(entry.result_json) : nil
+              return [ entry.completed ? :replay : :pending, value, entry.digest, entry.claim_token ]
+            end
+          end
+
+          # Record only while this token owns a live claim. JSON encoding rejects
+          # unsupported Ruby objects before writing; it never invokes Marshal.
+          def record(key, result, claim_token:)
+            json = JSON.generate(JsonValue.copy(result))
+            @model.where(key: key, claim_token: claim_token).where("expires_at > ?", @clock.call)
+              .update_all(result_json: json, completed: true)
+            nil
+          rescue ArgumentError, JSON::GeneratorError => error
+            raise ConfigurationError, "idempotency result must be a JSON value: #{error.message}"
+          end
+
+          # Delete expired claims, returning the number removed. Call from a host
+          # maintenance task; expiry of the requested key never needs this sweep.
+          def delete_expired
+            @model.where("expires_at <= ?", @clock.call).delete_all
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openui/rails/actions/idempotency/memory_store.rb

@@ -7,8 +7,8 @@ module OpenUI
     module Actions
       module Idempotency
         # Default, single-process idempotency store. Hosts that run multiple
-        # processes should inject a shared store (e.g. Redis or the database)
-        # that implements the same contract.
+        # processes can opt into ActiveRecordStore on SQLite
+        # or inject another shared adapter implementing the same contract.
         #
         # Contract:
         #   claim(key, ttl:, digest:) -> [status, result, digest, claim_token]

data/lib/openui/rails/actions.rb

@@ -13,6 +13,9 @@ module OpenUI
     # a host authorizer, stale-surface protection and idempotency, shared by
     # both component actions and browser tool calls.
     module Actions
+      module Idempotency
+        autoload :ActiveRecordStore, "openui/rails/actions/idempotency/active_record_store"
+      end
     end
   end
 end

data/lib/openui/rails/instrumentation.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "active_support/notifications"
+
+module OpenUI
+  module Rails
+    # Internal publisher for the documented, content-free notification contract.
+    module Instrumentation # :nodoc:
+      def self.now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def self.publish(name, started:, **metadata)
+        # Do not wrap application code in instrument's block: Active Support
+        # would attach the raw exception and its message if that code raised.
+        ActiveSupport::Notifications.instrument("#{name}.openui_rails",
+          **metadata, duration_ms: (now - started) * 1000)
+      rescue StandardError
+        # Observability must not change a business result or mask its exception.
+        nil
+      end
+
+      def self.action_error_code(error)
+        case error
+        when UnknownActionError then "unknown_action"
+        when UnauthorizedActionError then "unauthorized"
+        when StaleSurfaceError then "stale_surface"
+        when ReplayError then "replay"
+        when InvalidActionError then "invalid_action"
+        when Error then "error"
+        else "internal_error"
+        end
+      end
+    end
+  end
+end

data/lib/openui/rails/stream/bridge.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "openui/rails/instrumentation"
+
 module OpenUI
   module Rails
     module Stream
@@ -107,6 +109,7 @@ module OpenUI
             @total_bytes = 0
             @pending = +""
             @terminated = false
+            @started = Instrumentation.now
           end
 
           # Append a chunk and return a delta once the pending threshold is reached.
@@ -131,7 +134,8 @@ module OpenUI
             [ flush_delta ]
           end
 
-          # Flush pending text and emit the completion envelope once.
+          # Flush pending text and emit the completion envelope once. A terminal
+          # stream.openui_rails notification describes creation, not delivery.
           #
           # @return [Array<Envelope>] the final delta, if any, and completion
           def finish
@@ -144,6 +148,7 @@ module OpenUI
             )
             @sequence += 1
             @terminated = true
+            notify_termination("completed")
             envelopes
           end
 
@@ -184,8 +189,14 @@ module OpenUI
             @sequence += 1
             @terminated = true
             @pending.clear
+            notify_termination(code == "stream_cancelled" ? "cancelled" : "failed", code)
             envelope
           end
+
+          def notify_termination(outcome, code = nil)
+            Instrumentation.publish("stream", started: @started, outcome: outcome,
+              code: code, sequence: @sequence - 1, bytes: @total_bytes)
+          end
         end
       end
     end

data/lib/openui/rails/testing/idempotency_store_contract.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module OpenUI
+  module Rails
+    module Testing
+      # Reusable Minitest contract for idempotency adapters. Include this module
+      # in a test case that defines build_store and advance_store_clock(seconds).
+      # Each test needs an empty store and a controllable shared clock.
+      module IdempotencyStoreContract
+        def test_claim_distinguishes_pending_from_completed
+          store = build_store
+          status, value, digest, token = store.claim("key", ttl: 60, digest: "original")
+          assert_equal :claimed, status
+          assert_nil value
+          assert_equal "original", digest
+          refute_empty token
+          assert_equal [ :pending, nil, "original", token ], store.claim("key", ttl: 60, digest: "changed")
+          store.record("key", "saved", claim_token: token)
+          assert_equal [ :replay, "saved", "original", token ], store.claim("key", ttl: 60, digest: "changed")
+        end
+
+        def test_completed_nil_and_false_replay
+          store = build_store
+          [ nil, false ].each_with_index do |value, index|
+            key = "nullable-#{index}"
+            token = store.claim(key, ttl: 60, digest: "d").last
+            store.record(key, value, claim_token: token)
+            assert_equal [ :replay, value, "d", token ], store.claim(key, ttl: 60, digest: "d")
+          end
+        end
+
+        def test_json_results_round_trip
+          store = build_store
+          value = { "list" => [ 1, 2.5, true, false, nil, "你好" ], "nested" => { "ok" => true } }
+          token = store.claim("key", ttl: 60, digest: "d").last
+          store.record("key", value, claim_token: token)
+          assert_equal value, store.claim("key", ttl: 60, digest: "d")[1]
+        end
+
+        def test_expired_owner_cannot_record
+          store = build_store
+          token = store.claim("key", ttl: 10, digest: "old").last
+          advance_store_clock(10)
+          store.record("key", "late", claim_token: token)
+          status, value, _, replacement = store.claim("key", ttl: 60, digest: "new")
+          assert_equal :claimed, status
+          assert_nil value
+          refute_equal token, replacement
+        end
+
+        def test_replaced_owner_cannot_overwrite
+          store = build_store
+          old = store.claim("key", ttl: 10, digest: "old").last
+          advance_store_clock(11)
+          token = store.claim("key", ttl: 60, digest: "new").last
+          store.record("key", "new result", claim_token: token)
+          store.record("key", "old result", claim_token: old)
+          assert_equal [ :replay, "new result", "new", token ], store.claim("key", ttl: 60, digest: "new")
+        end
+
+        def test_wrong_token_and_unknown_key_do_not_complete_a_claim
+          store = build_store
+          token = store.claim("key", ttl: 60, digest: "d").last
+          store.record("missing", "value", claim_token: token)
+          store.record("key", "value", claim_token: "wrong")
+          assert_equal :pending, store.claim("key", ttl: 60, digest: "d").first
+          assert_equal :claimed, store.claim("missing", ttl: 60, digest: "d").first
+        end
+
+        def test_ttl_must_be_positive_and_finite
+          store = build_store
+          [ 0, -1, Float::INFINITY, Float::NAN, "60", nil ].each do |ttl|
+            assert_raises(OpenUI::Rails::ConfigurationError) { store.claim("key", ttl: ttl, digest: "d") }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openui/rails/version.rb

@@ -1,5 +1,5 @@
 module OpenUI
   module Rails
-    VERSION = "0.3.0"
+    VERSION = "0.5.0"
   end
 end

data/lib/openui/rails.rb

@@ -14,6 +14,7 @@ module OpenUI
 end
 
 require "openui/rails/errors"
+require "openui/rails/instrumentation"
 require "openui/rails/json_value"
 require "openui/rails/library_manifest"
 require "openui/rails/prompt_builder"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: openui-rails
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Andy Wang
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-19 00:00:00.000000000 Z
+date: 2026-10-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -80,12 +80,15 @@ files:
 - examples/support_desk/config/routes.rb
 - examples/support_desk/db/migrate/20261019000000_create_support_desk.rb
 - examples/support_desk/install.rb
+- lib/generators/openui/idempotency/idempotency_generator.rb
+- lib/generators/openui/idempotency/templates/create_openui_action_claims.rb
 - lib/generators/openui/install/install_generator.rb
 - lib/generators/openui/install/templates/config/initializers/openui.rb.tt
 - lib/generators/openui/install/templates/config/openui/README.md
 - lib/openui/rails.rb
 - lib/openui/rails/actions.rb
 - lib/openui/rails/actions/dispatcher.rb
+- lib/openui/rails/actions/idempotency/active_record_store.rb
 - lib/openui/rails/actions/idempotency/memory_store.rb
 - lib/openui/rails/actions/invocation.rb
 - lib/openui/rails/actions/registry.rb
@@ -101,6 +104,7 @@ files:
 - lib/openui/rails/doctor.rb
 - lib/openui/rails/engine.rb
 - lib/openui/rails/errors.rb
+- lib/openui/rails/instrumentation.rb
 - lib/openui/rails/json_value.rb
 - lib/openui/rails/library_manifest.rb
 - lib/openui/rails/message.rb
@@ -116,6 +120,7 @@ files:
 - lib/openui/rails/stream/transports/memory.rb
 - lib/openui/rails/stream/transports/turbo_streams.rb
 - lib/openui/rails/surface.rb
+- lib/openui/rails/testing/idempotency_store_contract.rb
 - lib/openui/rails/version.rb
 - lib/openui/rails/view_helper.rb
 - lib/tasks/openui.rake