rails_tool_views 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8d13afb04c0aa3830428d6bf43ad18936b5e5f676bdf80b8bed717fdb5dc5aa
-  data.tar.gz: 39be934d3e43b6f7380f89ce42faf3b67ea49f93eebec65fc551dbc3d944fbc4
+  metadata.gz: 5f0b45e8093744ab3053cb621e1b8118ef6c618b98f907e8e88b9b16f5b36fba
+  data.tar.gz: '05959be24f98969c883260f0b06cef6815d812393bf7c250d0d1dea1cc552e7b'
 SHA512:
-  metadata.gz: b7b9b32baaf39558ba998750dd4a181f0be83594ba71a8e21c5407b784960249f17ec8f9d551ea3e863751abd8032f12b7a548a0d447f26bffe4538a0a3b3d43
-  data.tar.gz: 2f53bf0cd980e42ee9175115b64b908face277ae907efaafbf7c21a15b70f4c97476dd45093f8d32220041567308f1f6b90c7385d60d268cc0d1e6bf8041e865
+  metadata.gz: 57ab0c782013453cc510f47402fcdae2b934a06fe69760b45411466b543c851d7b8b84e653bcef7824f3267f97319783e712754b7c321b9bd844826645f94afe
+  data.tar.gz: 2d741cf1b44e389bb3cc7a00bcf1de0da70ef3377077950fed1c4a166d9a62d7ac3ae339550779616b2c414ed23b8612531b2d2fda01f10e462cbc40d7ba6b5b

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.3.0] - 2026-10-19
+
+- Opt-in scoped `purge_closed` preview/apply with deadlines, bounded batches, atomic receipt cleanup and durable correlation tombstones. Host business records stay intact.
+
+- Add explicit host-authorized `close` and `abandon`, with read-only closed rendering, preserved exact action replay and first-termination retention deadlines.
+- Add lifecycle snapshot metadata and an additive migration. Stop old workers before upgrading; rollback refuses once a Surface was closed.
+- Coordinate delivery claims and lifecycle changes through the Surface lock while keeping callbacks outside transactions. Quarantine ambiguous lease takeovers and legacy multiple-attempt histories from cleanup.
+
 ## [0.2.0] - 2026-10-18
 
 - Add `rails_tool_views:component NAME` for a Partial, closed registration schemas and a Minitest scaffold. Component and action policies deny by default. Existing paths, unsafe names and symlink escapes are refused before writing.

data/app/helpers/rails_tool_views/surfaces_helper.rb

@@ -5,6 +5,8 @@ module RailsToolViews
     # Engine-owned copy. Translate or reword any of it under rails_tool_views.surface.<key>.
     TEXT = {
       page_title: "Interactive view", page_error_title: "Unable to complete this request", reload: "Reload saved view",
+      closed_title: "View closed.", abandoned_title: "View abandoned.", closed_help: "Saved actions are read-only. Start a new view to continue.",
+      agent_abandoned: "AI follow-up abandoned by the application.",
       ready: "View ready.", saved: "Changes saved.", revision: "Saved revision %{revision}",
       saving: "Saving changes…", save_failed: "Changes could not be saved. Review the message and try again.",
       agent_pending: "AI follow-up pending.", agent_completed: "AI follow-up completed.",
@@ -56,6 +58,7 @@ module RailsToolViews
     end
 
     def rails_tool_views_body(surface, definition, error: nil) # :nodoc:
+      return render(partial: "rails_tool_views/surfaces/closed", formats: [:html], locals: { surface: surface }) if surface.closed?
       html = if definition.partial
         render(partial: definition.partial, locals: { props: surface.props, state: surface.state, surface: surface, error: error })
       else

data/app/models/rails_tool_views/agent_interaction.rb

@@ -6,6 +6,8 @@ module RailsToolViews
     belongs_to :surface
     belongs_to :action_execution
     self.filter_attributes += %i[payload]
+    # Rails 7.2 cannot infer a SQLite boolean default written by Rails 8.1.
+    attribute :delivery_uncertain, :boolean, default: false
     attribute :payload, RedactedJson.new
     # Returns the stable host deduplication key across delivery retries.
     def delivery_key

data/app/models/rails_tool_views/surface.rb

@@ -15,9 +15,25 @@ module RailsToolViews
     def dom_id
       "rails_tool_views_surface_#{id}"
     end
+    # True once the host closes or abandons the view. Closed views cannot reopen.
+    def closed?
+      closed_at.present?
+    end
+    # True when payload cleanup has retained only the durable tombstone.
+    def purged?
+      purged_at.present?
+    end
+    # Returns the lifecycle independently of domain record or delivery status.
+    def lifecycle_status
+      return "purged" if purged?
+      return "abandoned" if abandoned_at
+      closed? ? "closed" : "active"
+    end
     # Returns the UI projection; it is not a permission grant.
     def snapshot
-      { id: id, component: component_key, component_digest: component_digest, props: props, state: state, revision: revision }
+      { id: id, component: component_key, component_digest: component_digest, props: props, state: state, revision: revision,
+        lifecycle: { status: lifecycle_status, closed_at: closed_at&.iso8601(6),
+          retain_until: retain_until&.iso8601(6), purged_at: purged_at&.iso8601(6) } }
     end
   end
 end

data/app/views/rails_tool_views/surfaces/_closed.html.erb

@@ -0,0 +1,2 @@
+<h2><%= rails_tool_views_text(surface.abandoned_at ? :abandoned_title : :closed_title) %></h2>
+<p><%= rails_tool_views_text(:closed_help) %></p>

data/app/views/rails_tool_views/surfaces/_surface.html.erb

@@ -8,7 +8,7 @@
   </p>
   <% interaction = surface.agent_interactions.order(:id).last %>
   <% if interaction && interaction.status != "skipped" %>
-    <p role="status"><%= rails_tool_views_text({ "pending" => :agent_pending, "delivering" => :agent_pending, "completed" => :agent_completed, "failed" => :agent_failed }.fetch(interaction.status, :agent_unavailable)) %></p>
+    <p role="status"><%= rails_tool_views_text({ "pending" => :agent_pending, "delivering" => :agent_pending, "completed" => :agent_completed, "failed" => :agent_failed, "abandoned" => :agent_abandoned }.fetch(interaction.status, :agent_unavailable)) %></p>
     <% if interaction.status == "failed" %>
       <%= form_with url: rails_tool_views_routes.surface_continuation_path(surface, interaction_id: interaction.id), method: :post do %>
         <button type="submit"><%= rails_tool_views_text(:agent_retry) %></button>

data/db/migrate/20261019000000_add_rails_tool_views_lifecycle.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+class AddRailsToolViewsLifecycle < ActiveRecord::Migration[7.2]
+  def up
+    add_column :rails_tool_views_surfaces, :closed_at, :datetime
+    add_column :rails_tool_views_surfaces, :abandoned_at, :datetime
+    add_column :rails_tool_views_surfaces, :retain_until, :datetime
+    add_column :rails_tool_views_surfaces, :purged_at, :datetime
+    add_index :rails_tool_views_surfaces, [:tenant_ref, :actor_ref, :closed_at], name: "index_rails_tool_views_retention_scope"
+    add_column :rails_tool_views_agent_interactions, :delivery_uncertain, :boolean, default: false, null: false
+    # Old rows do not distinguish explicit failed retries from lease takeovers.
+    # Preserve uncertainty instead of assuming an old callback has stopped.
+    execute "UPDATE rails_tool_views_agent_interactions SET delivery_uncertain = #{connection.quote(true)} WHERE attempts > 1 OR status = 'delivering'"
+  end
+
+  def down
+    if select_value("SELECT COUNT(*) FROM rails_tool_views_surfaces WHERE closed_at IS NOT NULL").to_i.positive?
+      raise ActiveRecord::IrreversibleMigration, "Closed or purged Surfaces cannot be safely reopened by an older runtime. Restore a pre-upgrade backup instead."
+    end
+    remove_column :rails_tool_views_agent_interactions, :delivery_uncertain
+    remove_index :rails_tool_views_surfaces, name: "index_rails_tool_views_retention_scope"
+    %i[closed_at abandoned_at retain_until purged_at].each { |column| remove_column :rails_tool_views_surfaces, column }
+  end
+end

data/lib/generators/rails_tool_views/install/install_generator.rb

@@ -12,6 +12,7 @@ module RailsToolViews
       end
       def install
         migration_template "create_rails_tool_views.rb", "db/migrate/create_rails_tool_views.rb"
+        migration_template "add_rails_tool_views_lifecycle.rb", "db/migrate/add_rails_tool_views_lifecycle.rb"
         template "rails_tool_views.rb", "config/initializers/rails_tool_views.rb"
         route 'mount RailsToolViews::Engine => "/rails_tool_views", as: :rails_tool_views'
       end

data/lib/generators/rails_tool_views/install/templates/add_rails_tool_views_lifecycle.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+class AddRailsToolViewsLifecycle < ActiveRecord::Migration[7.2]
+  def up
+    add_column :rails_tool_views_surfaces, :closed_at, :datetime
+    add_column :rails_tool_views_surfaces, :abandoned_at, :datetime
+    add_column :rails_tool_views_surfaces, :retain_until, :datetime
+    add_column :rails_tool_views_surfaces, :purged_at, :datetime
+    add_index :rails_tool_views_surfaces, [:tenant_ref, :actor_ref, :closed_at], name: "index_rails_tool_views_retention_scope"
+    add_column :rails_tool_views_agent_interactions, :delivery_uncertain, :boolean, default: false, null: false
+    # Old rows do not distinguish explicit failed retries from lease takeovers.
+    # Preserve uncertainty instead of assuming an old callback has stopped.
+    execute "UPDATE rails_tool_views_agent_interactions SET delivery_uncertain = #{connection.quote(true)} WHERE attempts > 1 OR status = 'delivering'"
+  end
+
+  def down
+    if select_value("SELECT COUNT(*) FROM rails_tool_views_surfaces WHERE closed_at IS NOT NULL").to_i.positive?
+      raise ActiveRecord::IrreversibleMigration, "Closed or purged Surfaces cannot be safely reopened by an older runtime. Restore a pre-upgrade backup instead."
+    end
+    remove_column :rails_tool_views_agent_interactions, :delivery_uncertain
+    remove_index :rails_tool_views_surfaces, name: "index_rails_tool_views_retention_scope"
+    %i[closed_at abandoned_at retain_until purged_at].each { |column| remove_column :rails_tool_views_surfaces, column }
+  end
+end

data/lib/rails_tool_views/core.rb

@@ -13,6 +13,11 @@ module RailsToolViews
     MESSAGES = {
       "NOT_FOUND" => "This view is unavailable.", "NOT_ALLOWED" => "You do not have permission to use this view.",
       "CONFLICT" => "This view changed. Refresh to continue.", "INVALID_ARGUMENTS" => "Check the submitted values and try again.",
+      "SURFACE_CLOSED" => "This view is closed. Its saved actions cannot be changed.",
+      "SURFACE_PURGED" => "This view has been cleaned up and cannot be restored.",
+      "LIFECYCLE_BUSY" => "This view has unfinished or uncertain delivery. Resolve it before closing.",
+      "INVALID_RETENTION_REQUEST" => "Choose an explicit past cutoff and a batch size from 1 to 1000.",
+      "INVALID_RETENTION_WINDOW" => "Choose a future retention deadline or keep this view indefinitely.",
       "VALIDATION_FAILED" => "Check the highlighted fields and try again.",
       "INCOMPATIBLE_COMPONENT" => "This view's contract changed. Ask the application owner to migrate or recreate it.",
       "RENDER_FAILED" => "This view cannot be rendered. Your saved state is preserved.",
@@ -249,7 +254,7 @@ module RailsToolViews
   # Process-local host hooks, request limits, and delivery settings.
   class Configuration
     attr_accessor :scope_resolver, :agent_adapter, :max_payload_bytes, :max_depth, :max_catalog_components, :max_actions_per_minute, :auto_deliver,
-      :parent_controller, :delivery_lease
+      :parent_controller, :delivery_lease, :retention_policy
     # Initializes conservative request limits with no host identity or agent adapter.
     def initialize
       @max_payload_bytes, @max_depth, @max_catalog_components, @max_actions_per_minute = 32_768, 16, 20, 60

data/lib/rails_tool_views/lifecycle.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+module RailsToolViews
+  class << self
+    # Closes a view after host authorization. Outstanding continuation work blocks
+    # closure. nil retain_until keeps data indefinitely; the first closure wins.
+    def close(id, scope:, retain_until: nil)
+      finish_surface(id, scope: scope, retain_until: retain_until, abandon: false)
+    end
+
+    # Explicitly abandons pending/failed continuation work before closing a view.
+    # In-flight or historically uncertain delivery is never abandoned implicitly.
+    def abandon(id, scope:, retain_until: nil)
+      finish_surface(id, scope: scope, retain_until: retain_until, abandon: true)
+    end
+
+    # Scrubs eligible closed payloads in one bounded batch, preserving replay
+    # tombstones. Requires an explicit scope, cutoff and host retention policy.
+    # Defaults to a read-only preview. Each applied Surface commits atomically.
+    def purge_closed(scope:, closed_before:, batch_size: 100, dry_run: true)
+      check_scope!(scope)
+      valid_time = closed_before.is_a?(Time) || closed_before.is_a?(ActiveSupport::TimeWithZone)
+      unless valid_time && closed_before <= Time.current && batch_size.is_a?(Integer) && batch_size.between?(1, 1000) && [true, false].any? { |v| dry_run.equal?(v) }
+        raise Error.new("INVALID_RETENTION_REQUEST")
+      end
+      policy = configuration.retention_policy
+      raise Error.new("NOT_ALLOWED", status: 403) unless policy.respond_to?(:call)
+      now = Time.current
+      candidates = Surface.where(actor_ref: scope.actor, tenant_ref: scope.tenant, purged_at: nil)
+        .where("closed_at < ? AND retain_until <= ?", closed_before, now).order(:closed_at, :id).limit(batch_size).pluck(:id)
+      counts = { examined: 0, eligible: 0, purged: 0, protected: 0, dry_run: dry_run }
+      candidates.each do |id|
+        surface = Surface.find_by(id: id)
+        next unless surface
+        surface.with_lock do
+          counts[:examined] += 1
+          eligible = exact_match?(surface, actor_ref: scope.actor, tenant_ref: scope.tenant) &&
+            !surface.purged? && surface.closed? && surface.closed_at < closed_before &&
+            surface.retain_until && surface.retain_until <= now
+          if eligible
+            request = access(scope, :purge, surface: surface, props: surface.props, context_ref: surface.context_ref)
+            eligible = policy.call(request) == true && !protected_interactions?(surface, abandon: false)
+          end
+          unless eligible
+            counts[:protected] += 1
+            next
+          end
+          counts[:eligible] += 1
+          next if dry_run
+          # The Surface lock excludes action commits, delivery claims and other
+          # cleanup workers. Only known terminal children are removed together.
+          surface.agent_interactions.delete_all
+          surface.action_executions.delete_all
+          surface.update!(props: {}, state: {}, context_ref: nil, purged_at: now)
+          counts[:purged] += 1
+        end
+      end
+      counts
+    end
+
+    private
+    def finish_surface(id, scope:, retain_until:, abandon:)
+      validate_retention_deadline!(retain_until, future: false)
+      surface = restore(id, scope: scope)
+      surface.with_lock do
+        ensure_not_purged!(surface)
+        component = compatible_component!(surface)
+        component.authorize!(access(scope, :read, surface: surface, props: surface.props, context_ref: surface.context_ref))
+        component.authorize!(access(scope, abandon ? :abandon : :close, surface: surface, props: surface.props, context_ref: surface.context_ref))
+        next if surface.closed?
+        validate_retention_deadline!(retain_until, future: true)
+        interactions = surface.agent_interactions
+        raise Error.new("LIFECYCLE_BUSY", status: 409) if protected_interactions?(surface, abandon: abandon)
+        if abandon
+          interactions.where(status: %w[pending failed]).update_all(status: "abandoned", claimed_at: nil, error_code: nil, updated_at: Time.current)
+        end
+        now = Time.current
+        surface.update!(closed_at: now, abandoned_at: abandon ? now : nil, retain_until: retain_until, revision: surface.revision + 1)
+      end
+      surface
+    end
+    def protected_interactions?(surface, abandon:)
+      interactions = surface.agent_interactions
+      allowed = abandon ? %w[completed skipped pending failed abandoned] : %w[completed skipped abandoned]
+      interactions.where(delivery_uncertain: true).exists? || interactions.where.not(status: allowed).exists?
+    end
+    def validate_retention_deadline!(deadline, future:)
+      return if deadline.nil?
+      valid_type = deadline.is_a?(Time) || deadline.is_a?(ActiveSupport::TimeWithZone)
+      raise Error.new("INVALID_RETENTION_WINDOW") unless valid_type && (!future || deadline > Time.current)
+    end
+  end
+end

data/lib/rails_tool_views/runtime.rb

@@ -44,6 +44,7 @@ module RailsToolViews
       # match may stand in for this scope's Surface, or a lookup could disclose
       # another actor's or tenant's record.
       raise Error.new("NOT_FOUND", status: 404) unless surface && exact_match?(surface, id: id.to_s, actor_ref: scope.actor, tenant_ref: scope.tenant)
+      ensure_not_purged!(surface)
       component = compatible_component!(surface)
       component.authorize!(access(scope, :read, surface: surface, props: surface.props, context_ref: surface.context_ref))
       surface
@@ -62,6 +63,7 @@ module RailsToolViews
       request_digest = Data.digest(action: definition.key, arguments: arguments, base_revision: base_revision)
       result = nil
       surface.with_lock do
+        ensure_not_purged!(surface)
         compatible_component!(surface).authorize!(access(scope, :read, surface: surface, props: surface.props, context_ref: surface.context_ref))
         request = access(scope, :action, surface: surface, props: surface.props, action: definition.key,
           arguments: arguments, context_ref: surface.context_ref)
@@ -74,6 +76,7 @@ module RailsToolViews
           result = prior.result.symbolize_keys
           next
         end
+        raise Error.new("SURFACE_CLOSED", status: 410) if surface.closed?
         raise Error.new("CONFLICT", status: 409) unless surface.revision == base_revision
         if surface.action_executions.where("created_at >= ?", 1.minute.ago).count >= configuration.max_actions_per_minute
           raise Error.new("RATE_LIMITED", status: 429)
@@ -114,25 +117,35 @@ module RailsToolViews
       interaction = AgentInteraction.find_by(id: id)
       raise Error.new("NOT_FOUND", status: 404) unless interaction
       surface = restore(interaction.surface_id, scope: scope)
-      definition = compatible_component!(surface).actions.fetch(interaction.payload.fetch("action")) { raise Error.new("INCOMPATIBLE_COMPONENT", status: 422) }
-      arguments = definition.schema.validate!(interaction.payload.fetch("values"), code: "INVALID_ARGUMENTS")
-      request = access(scope, :action, surface: surface, props: surface.props, action: definition.key, arguments: arguments, context_ref: surface.context_ref)
-      raise Error.new("NOT_ALLOWED", status: 403) unless definition.policy&.call(request) == true
       claimed = false
-      interaction.with_lock do
-        if %w[completed skipped].include?(interaction.status)
-          next
-        end
-        if interaction.status == "delivering" && interaction.claimed_at && interaction.claimed_at > Time.current - configuration.delivery_lease
-          next
-        end
-        next if interaction.status == "failed" && !retry_failed
-        if adapter.nil?
-          interaction.update!(status: "skipped")
-          next
+      # Coordinate the claim with close/abandon/purge, using the same lock order
+      # as actions. Never hold a database transaction during the adapter call.
+      surface.with_lock do
+        ensure_not_purged!(surface)
+        component = compatible_component!(surface)
+        component.authorize!(access(scope, :read, surface: surface, props: surface.props, context_ref: surface.context_ref))
+        interaction.with_lock do
+          definition = component.actions.fetch(interaction.payload.fetch("action")) { raise Error.new("INCOMPATIBLE_COMPONENT", status: 422) }
+          arguments = definition.schema.validate!(interaction.payload.fetch("values"), code: "INVALID_ARGUMENTS")
+          request = access(scope, :action, surface: surface, props: surface.props, action: definition.key, arguments: arguments, context_ref: surface.context_ref)
+          raise Error.new("NOT_ALLOWED", status: 403) unless definition.policy&.call(request) == true
+          next if %w[completed skipped abandoned].include?(interaction.status)
+          raise Error.new("SURFACE_CLOSED", status: 410) if surface.closed?
+          if interaction.status == "delivering" && interaction.claimed_at && interaction.claimed_at > Time.current - configuration.delivery_lease
+            next
+          end
+          next if interaction.status == "failed" && !retry_failed
+          # Reclaiming a lease does not prove that the previous callback ended.
+          # This durable flag cannot be cleared by a stale worker's completion.
+          uncertain = interaction.delivery_uncertain? || interaction.status == "delivering"
+          if adapter.nil?
+            interaction.update!(status: "skipped", claimed_at: nil, delivery_uncertain: uncertain)
+            next
+          end
+          interaction.update!(status: "delivering", claimed_at: Time.current, attempts: interaction.attempts + 1,
+            error_code: nil, delivery_uncertain: uncertain)
+          claimed = true
         end
-        interaction.update!(status: "delivering", claimed_at: Time.current, attempts: interaction.attempts + 1, error_code: nil)
-        claimed = true
       end
       return interaction.reload unless claimed
       begin
@@ -190,6 +203,9 @@ module RailsToolViews
     end
 
     private
+    def ensure_not_purged!(surface)
+      raise Error.new("SURFACE_PURGED", status: 410) if surface.purged?
+    end
     def check_scope!(scope)
       raise Error.new("INVALID_SCOPE", status: 403) unless scope.is_a?(Scope)
     end

data/lib/rails_tool_views/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module RailsToolViews
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/rails_tool_views.rb

@@ -3,4 +3,5 @@ require_relative "rails_tool_views/core"
 require "rails"
 require "rails/engine"
 require_relative "rails_tool_views/runtime"
+require_relative "rails_tool_views/lifecycle"
 require_relative "rails_tool_views/engine"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails_tool_views
 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: rails
@@ -179,22 +179,26 @@ files:
 - app/models/rails_tool_views/redacted_json.rb
 - app/models/rails_tool_views/surface.rb
 - app/views/layouts/rails_tool_views/application.html.erb
+- app/views/rails_tool_views/surfaces/_closed.html.erb
 - app/views/rails_tool_views/surfaces/_error.html.erb
 - app/views/rails_tool_views/surfaces/_surface.html.erb
 - app/views/rails_tool_views/surfaces/page.html.erb
 - config/routes.rb
 - db/migrate/20261010000000_create_rails_tool_views.rb
+- db/migrate/20261019000000_add_rails_tool_views_lifecycle.rb
 - lib/generators/rails_tool_views/component/component_generator.rb
 - lib/generators/rails_tool_views/component/templates/component_test.rb
 - lib/generators/rails_tool_views/component/templates/partial.html.erb
 - lib/generators/rails_tool_views/component/templates/registration.rb
 - lib/generators/rails_tool_views/install/install_generator.rb
+- lib/generators/rails_tool_views/install/templates/add_rails_tool_views_lifecycle.rb
 - lib/generators/rails_tool_views/install/templates/create_rails_tool_views.rb
 - lib/generators/rails_tool_views/install/templates/rails_tool_views.rb
 - lib/rails_tool_views.rb
 - lib/rails_tool_views/adapters/ruby_llm.rb
 - lib/rails_tool_views/core.rb
 - lib/rails_tool_views/engine.rb
+- lib/rails_tool_views/lifecycle.rb
 - lib/rails_tool_views/runtime.rb
 - lib/rails_tool_views/version.rb
 homepage: https://github.com/yorzi/rails_tool_views