ruby_llm-browser 0.1.0

data/lib/ruby_llm/browser/operation_store.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Browser
+    # Durable bookkeeping for browser operations.
+    #
+    # The host supplies an implementation. {InMemoryOperationStore} is a fixture for
+    # tests and single-process demos only; production multi-worker or restart-safe use
+    # requires a durable store (for example the ActiveRecord store in
+    # `ruby_llm/browser/rails`).
+    #
+    # Every method is expected to be atomic. Callers assume:
+    #
+    # - {#reserve} never starts two operations for one idempotency key
+    # - {#update} rejects a stale writer (fencing)
+    # - the reservation is held for `unknown` / `cleanup_pending`, not released early
+    class OperationStore
+      # Atomically stores a new operation and enforces the actor's concurrency budget.
+      # @raise [InvalidInput] the id already exists
+      # @raise [BudgetExhausted] the concurrency slot is taken
+      def reserve(_operation)
+        raise NotImplementedError, "OperationStore#reserve must be implemented"
+      end
+
+      # Returns the existing operation for the same actor/run/idempotency key, or
+      # reserves +operation+. Duplicate jobs must attach, never start a second session.
+      def attach_or_reserve(_operation)
+        raise NotImplementedError, "OperationStore#attach_or_reserve must be implemented"
+      end
+
+      # @return [Operation, nil]
+      def fetch(_id)
+        raise NotImplementedError, "OperationStore#fetch must be implemented"
+      end
+
+      # Returns the operation or raises {InvalidInput} when absent.
+      def fetch!(_id)
+        raise NotImplementedError, "OperationStore#fetch! must be implemented"
+      end
+
+      # Claims the operation for one worker, bumping its fence token.
+      #
+      # @return [Operation] the newly leased operation
+      # @raise [NotAuthorized] a different actor/run tries to claim it
+      def lease(_id, actor_id:, run_id:, now:)
+        raise NotImplementedError, "OperationStore#lease must be implemented"
+      end
+
+      # Persists +operation+ only if its fence is current.
+      #
+      # @return [Operation] the stored operation
+      # @raise [InvalidInput] the writer is fenced (stale)
+      def update(_operation)
+        raise NotImplementedError, "OperationStore#update must be implemented"
+      end
+
+      # Atomically changes reserved to starting, checking the caller's fence. A second
+      # delivery must never start even when it read the row before the first claim.
+      def claim_start(_operation, now:)
+        raise NotImplementedError, "OperationStore#claim_start must be implemented"
+      end
+
+      # Persists a returned session even if cancellation fenced its starting worker.
+      def record_session(_operation, session_id:, now:)
+        raise NotImplementedError, "OperationStore#record_session must be implemented"
+      end
+
+      # Records provider-confirmed closure of this exact session, including cancellation.
+      def confirm_closed(_operation, session_id:, now:)
+        raise NotImplementedError, "OperationStore#confirm_closed must be implemented"
+      end
+
+      # Marks an operation unable to confirm its own cleanup.
+      #
+      # @return [Operation]
+      def mark_cleanup_pending(_id, actor_id:, run_id:, error_code: nil, now:)
+        raise NotImplementedError, "OperationStore#mark_cleanup_pending must be implemented"
+      end
+
+      # @return [Array<Operation>] operations currently holding a slot for the actor
+      def open_for(_actor_id)
+        raise NotImplementedError, "OperationStore#open_for must be implemented"
+      end
+
+      # @return [Array<Operation>] every open operation across all actors. Used by the
+      #   cleanup reaper, which is a host-operated, system-wide sweep.
+      def open_operations
+        raise NotImplementedError, "OperationStore#open_operations must be implemented"
+      end
+    end
+  end
+end

data/lib/ruby_llm/browser/policy.rb

@@ -0,0 +1,298 @@
+# frozen_string_literal: true
+
+require "json"
+require "json_schemer"
+
+module RubyLLM
+  module Browser
+    # The host's source, schema, action and egress policy.
+    #
+    # Policy is composed by the host application and enforced by the Gem. It never
+    # infers permissions from model arguments or page text, and it fails closed: an
+    # unknown host, schema, action or an unqualified backend stops the operation.
+    class Policy
+      # JSON Schema keys this Gem accepts inside an extraction schema.
+      SCHEMA_KEYS = %w[
+        type description properties required items enum
+        additionalProperties title minimum maximum
+        minLength maxLength minItems maxItems
+        format default
+      ].freeze
+
+      ALLOWED_SCHEMA_TYPES = %w[object array string integer number boolean null].freeze
+
+      # Action methods an approved Act may use. There is no keypress/execute/download and
+      # no arbitrary JavaScript.
+      DEFAULT_ACTION_METHODS = %w[click fill press select_option check uncheck hover].freeze
+
+      # Sensitive operations are refused even with a broad host approval.
+      DEFAULT_FORBIDDEN_ACTIONS = [
+        /\b(?:purchase|buy|checkout|pay(?:ment)?|place[-_ ]?order|subscribe|billing)\b/i,
+        /\b(?:post|publish|tweet|toot|comment|reply|send(?:[-\s]?message)?|submit|share)\b/i,
+        /\b(?:delete|destroy|remove|deactivate|close[-_ ]?account|cancel[-_ ]?account|unsubscribe)\b/i,
+        /\b(?:password|passwd|credential|api[-_ ]?key|secret|credit[-_ ]?card|cvv|ssn|passport)\b/i,
+        /\b(?:sign[-\s]?in|log[-\s]?in|log[-\s]?out|authenticate|sign[-\s]?up|register|2fa|otp)\b/i,
+        /\b(?:transfer|withdraw|refund|donate)\b/i
+      ].freeze
+
+      DEFAULT_MAX_SCHEMA_DEPTH = 8
+      DEFAULT_MAX_SCHEMA_PROPERTIES = 64
+      DEFAULT_MAX_SCHEMA_BYTES = 16_384
+
+      attr_reader :allowed_hosts, :allowed_schemes, :allowed_ports, :max_result_bytes,
+                  :allowed_action_methods, :forbidden_action_patterns,
+                  :max_schema_depth, :max_schema_properties, :max_schema_bytes
+
+      def initialize(allowed_hosts:, allowed_schemes: UrlGuard::DEFAULT_SCHEMES,
+                     allowed_ports: UrlGuard::DEFAULT_PORTS, verify_dns: true, resolver: nil,
+                     max_result_bytes: nil,
+                     allowed_action_methods: DEFAULT_ACTION_METHODS,
+                     forbidden_action_patterns: DEFAULT_FORBIDDEN_ACTIONS,
+                     max_schema_depth: DEFAULT_MAX_SCHEMA_DEPTH,
+                     max_schema_properties: DEFAULT_MAX_SCHEMA_PROPERTIES,
+                     max_schema_bytes: DEFAULT_MAX_SCHEMA_BYTES)
+        @url_guard = UrlGuard.new(
+          allowed_hosts: allowed_hosts, allowed_schemes: allowed_schemes,
+          allowed_ports: allowed_ports, verify_dns: verify_dns, resolver: resolver
+        )
+        @allowed_hosts = @url_guard.allowed_hosts
+        @allowed_schemes = @url_guard.allowed_schemes
+        @allowed_ports = @url_guard.allowed_ports
+        @max_result_bytes = positive_integer!(max_result_bytes || RubyLLM::Browser.configuration.max_result_bytes, :max_result_bytes)
+        @allowed_action_methods = Immutable.copy(normalize_action_methods!(allowed_action_methods))
+        @forbidden_action_patterns = (DEFAULT_FORBIDDEN_ACTIONS + Array(forbidden_action_patterns)).uniq.map do |pattern|
+          raise InvalidInput, "forbidden actions must be regexps" unless pattern.is_a?(Regexp)
+
+          pattern
+        end.freeze
+        @max_schema_depth = positive_integer!(max_schema_depth, :max_schema_depth)
+        @max_schema_properties = positive_integer!(max_schema_properties, :max_schema_properties)
+        @max_schema_bytes = positive_integer!(max_schema_bytes, :max_schema_bytes)
+        freeze
+      end
+
+      # Authorizes and normalizes a destination URL.
+      #
+      # @return [URI::Generic]
+      # @raise [InvalidInput] malformed or ambiguous URL
+      # @raise [NotAuthorized] policy denial
+      def authorize_destination!(url, actor_id: nil)
+        @url_guard.authorize!(url)
+      end
+
+      # Validates a model-supplied extraction schema: an object schema, bounded in depth,
+      # properties and bytes, using only known keys and types.
+      #
+      # @return [Hash] the schema (JSON string keys)
+      def authorize_schema!(schema)
+        schema = coerce_schema!(schema)
+        raise InvalidInput, "extraction schema must be an object schema" unless schema.is_a?(Hash)
+        json = Redactor.canonical_json(schema)
+        raise InvalidInput, "extraction schema is too large" if json.bytesize > max_schema_bytes
+        raise InvalidInput, "extraction schema must be an object schema" unless schema["type"] == "object"
+
+        validate_schema_node!(schema, depth: 1)
+        unless JSONSchemer.valid_schema?(schema)
+          raise InvalidInput, "extraction schema is malformed"
+        end
+        properties = schema["properties"] || {}
+        if properties.size > max_schema_properties
+          raise InvalidInput, "extraction schema has too many properties"
+        end
+
+        Immutable.copy(schema)
+      rescue JSON::GeneratorError, JSON::NestingError, SystemStackError
+        raise InvalidInput, "extraction schema is not bounded JSON"
+      end
+
+      # Rejects provider data that does not satisfy the host's JSON Schema.
+      def authorize_extraction!(data, schema:)
+        raise ProviderError, "browser extraction did not match the host schema" unless JSONSchemer.schema(schema).valid?(data)
+
+        data
+      end
+
+      # Redacts and bounds arbitrary extraction/observation data.
+      #
+      # @return [Array(Object, Boolean)] bounded data and truncation flag
+      def authorize_result!(data, max_bytes: nil, secrets: [])
+        Redactor.bound(data, max_bytes: [ max_bytes || max_result_bytes, max_result_bytes ].min, secrets: secrets)
+      end
+
+      # Validates one observed/approved action hash.
+      #
+      # @return [Hash] the normalized action (`description`, `method`, `selector`, `arguments`)
+      def authorize_action!(action)
+        action = symbolize_action!(action)
+        method = action.fetch("method", nil)&.to_s&.downcase
+        selector = action["selector"].to_s
+        description = action["description"].to_s
+        arguments = Array(action["arguments"]).map(&:to_s)
+
+        raise InvalidInput, "action method is required" if method.to_s.empty?
+        raise InvalidInput, "action selector is required" if selector.empty?
+        unless allowed_action_methods.include?(method)
+          raise NotAuthorized, "action method #{method.inspect} is not allowed"
+        end
+
+        haystack = ([ description, selector ] + arguments).join(" ")
+        if forbidden_action_patterns.any? { |pattern| pattern.match?(haystack) }
+          raise NotAuthorized, "action is outside the allowed, non-sensitive set"
+        end
+
+        {
+          "description" => description.empty? ? "#{method} #{selector}" : description,
+          "method" => method,
+          "selector" => selector,
+          "arguments" => arguments
+        }
+      end
+
+      # True when a backend proves the egress isolation this Gem requires.
+      def egress_qualified?(capabilities)
+        return false unless capabilities.is_a?(Capabilities)
+        return false unless capabilities.enforced_egress?
+        return false if capabilities.local_mode? && !capabilities.local_binary_pinned?
+        return false if capabilities.custom_headers_present? && !capabilities.custom_headers_approved?
+
+        true
+      end
+
+      # Raises unless the backend is egress-qualified. Called before any session starts.
+      def authorize_egress!(capabilities)
+        return true if egress_qualified?(capabilities)
+
+        raise UnsupportedSecurityCapability, egress_failure_reason(capabilities)
+      end
+
+      def to_h
+        {
+          allowed_hosts: allowed_hosts,
+          allowed_schemes: allowed_schemes,
+          allowed_ports: allowed_ports,
+          max_result_bytes: max_result_bytes,
+          allowed_action_methods: allowed_action_methods,
+          max_schema_depth: max_schema_depth
+        }
+      end
+
+      def digest = Redactor.digest(to_h)
+
+      private
+
+      def egress_failure_reason(capabilities)
+        return "backend did not report capabilities" unless capabilities.is_a?(Capabilities)
+
+        reasons = []
+        reasons << "browser egress isolation is not enforced" unless capabilities.enforced_egress?
+        if capabilities.local_mode? && !capabilities.local_binary_pinned?
+          reasons << "local mode requires a host-pinned server binary"
+        end
+        if capabilities.custom_headers_present? && !capabilities.custom_headers_approved?
+          reasons << "STAGEHAND_CUSTOM_HEADERS is set but not host-approved"
+        end
+        "backend cannot enforce egress isolation: #{reasons.join("; ")}"
+      end
+
+      def coerce_schema!(schema)
+        case schema
+        when Hash
+          stringify_keys(schema)
+        when String
+          parse_schema_json!(schema)
+        when Class
+          if schema.respond_to?(:to_json_schema)
+            return stringify_keys(schema.to_json_schema)
+          end
+          if schema.instance_methods.include?(:to_json_schema)
+            return stringify_keys(schema.new.to_json_schema)
+          end
+          raise InvalidInput, "unsupported schema class"
+        else
+          if schema.respond_to?(:to_json_schema)
+            stringify_keys(schema.to_json_schema)
+          else
+            raise InvalidInput, "extraction schema must be a Hash or JSON object string"
+          end
+        end
+      end
+
+      def parse_schema_json!(string)
+        raise InvalidInput, "extraction schema is too large" if string.bytesize > max_schema_bytes
+
+        parsed = JSON.parse(string)
+        raise InvalidInput, "extraction schema must be a JSON object" unless parsed.is_a?(Hash)
+
+        stringify_keys(parsed)
+      rescue JSON::ParserError
+        raise InvalidInput, "extraction schema is not valid JSON", cause: nil
+      end
+
+      def validate_schema_node!(node, depth:)
+        return unless node.is_a?(Hash) || node.is_a?(Array)
+
+        if depth > max_schema_depth
+          raise InvalidInput, "extraction schema is nested too deeply"
+        end
+
+        case node
+        when Array
+          node.each { |item| validate_schema_node!(item, depth: depth + 1) }
+        when Hash
+          node.each do |key, value|
+            name = key.to_s
+            unless SCHEMA_KEYS.include?(name)
+              raise InvalidInput, "unsupported schema key #{name.inspect}"
+            end
+            validate_schema_type!(value) if name == "type"
+            if name == "properties"
+              # Values are schemas; property names themselves are arbitrary.
+              value.each_value { |subschema| validate_schema_node!(subschema, depth: depth + 1) } if value.is_a?(Hash)
+            elsif name == "items" || name == "additionalProperties"
+              validate_schema_node!(value, depth: depth + 1)
+            end
+          end
+        end
+      end
+
+      def validate_schema_type!(value)
+        types = Array(value).map(&:to_s)
+        invalid = types - ALLOWED_SCHEMA_TYPES
+        raise InvalidInput, "unsupported schema type #{invalid.inspect}" if invalid.any?
+      end
+
+      def symbolize_action!(action)
+        raise InvalidInput, "action must be a Hash" unless action.is_a?(Hash)
+
+        action.each_with_object({}) { |(key, value), result| result[key.to_s] = value }
+      end
+
+      def stringify_keys(value)
+        case value
+        when Hash
+          value.each_with_object({}) { |(key, nested), result| result[key.to_s] = stringify_keys(nested) }
+        when Array
+          value.map { |item| stringify_keys(item) }
+        else
+          value
+        end
+      end
+
+      def normalize_action_methods!(methods)
+        normalized = Array(methods).map { |method| method.to_s.downcase }
+        raise InvalidInput, "allowed_action_methods must not be empty" if normalized.empty?
+        unless (normalized - DEFAULT_ACTION_METHODS).empty?
+          raise InvalidInput, "only supported non-script action methods are allowed"
+        end
+
+        normalized.uniq
+      end
+
+      def positive_integer!(value, name)
+        raise InvalidInput, "#{name} must be a positive integer" unless value.is_a?(Integer) && value.positive?
+
+        value
+      end
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Browser
+    module Rails
+      # Durable {RubyLLM::Browser::ApprovalStore} backed by ActiveRecord.
+      #
+      # {#consume_once} performs every check and uses a conditional database update:
+      # existence, active, actor/run, URL, page revision, operation/session and exact
+      # action digest — before it marks the row consumed. Two workers cannot both consume
+      # the same grant, and a replayed or cross-actor approval is refused.
+      class ActiveRecordApprovalStore < ApprovalStore
+        def initialize(record_class: ApprovalRecord)
+          super()
+          @record_class = record_class
+        end
+
+        def issue(approval)
+          @record_class.create!(
+            id: approval.id, actor_id: approval.actor_id, run_id: approval.run_id,
+            url: approval.url, action_digest: approval.action_digest,
+            action: @record_class.dump_action(approval.action),
+            page_revision: approval.page_revision, operation_id: approval.operation_id,
+            session_id: approval.session_id, issued_at: approval.issued_at,
+            expires_at: approval.expires_at, consumed_at: approval.consumed_at,
+            revoked: approval.revoked?, created_at: approval.issued_at,
+            updated_at: approval.issued_at
+          )
+          approval
+        rescue ActiveRecord::RecordNotUnique
+          raise InvalidInput, "approval #{approval.id} already exists"
+        end
+
+        def fetch(id)
+          @record_class.find_by(id: id)&.to_approval
+        end
+
+        def consume_once(id, actor_id:, run_id:, url:, action_digest:, now:, page_revision: nil,
+                         operation_id: nil, session_id: nil)
+          record = @record_class.find_by(id: id)
+          raise ApprovalRequired, "no approval was issued" unless record
+            approval = record.to_approval
+            raise ApprovalStale, "approval #{id} was already consumed" if approval.consumed?
+            raise ApprovalStale, "approval #{id} was revoked" if approval.revoked?
+            raise ApprovalStale, "approval #{id} has expired" if approval.expired?(now)
+
+            unless approval.binding_matches?(
+              actor_id: actor_id, run_id: run_id, url: url, action_digest: action_digest,
+              page_revision: page_revision, operation_id: operation_id, session_id: session_id
+            )
+              raise ApprovalStale, "approval #{id} does not authorize this actor, URL, page or action"
+            end
+
+            consumed = approval.consume!(now: now)
+            changed = @record_class.where(id: id, consumed_at: nil, revoked: false)
+                                   .where("expires_at > ?", now)
+                                   .update_all(consumed_at: now, updated_at: now)
+            raise ApprovalStale, "approval is no longer active" unless changed == 1
+
+            consumed
+        end
+
+        def revoke(id)
+          changed = @record_class.where(id: id).update_all(revoked: true, updated_at: Time.now.utc)
+          raise ApprovalRequired, "no approval was issued" if changed.zero?
+
+          fetch(id)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Browser
+    module Rails
+      # Durable, multi-worker {RubyLLM::Browser::OperationStore} backed by ActiveRecord.
+      #
+      # Supports SQLite and PostgreSQL. Reservations acquire a durable per-actor write
+      # lock, including when the actor has no existing operations. Worker writes check
+      # the exact fence and legal transition. No database transaction spans network I/O.
+      #
+      # - a duplicate reservation loses the unique-index race and is reported as
+      #   {InvalidInput} instead of silently starting a second session
+      # - a duplicated worker that re-leases an operation bumps its fence, and any
+      #   earlier writer is then refused as stale (fenced out)
+      # - a cancelled operation keeps its row and reservation until closure/expiry is
+      #   proven; cancellation fences stale workers by bumping the fence
+      #
+      # The store never interprets provider truth: it records the states the engine and
+      # reaper report.
+      class ActiveRecordOperationStore < OperationStore
+        def initialize(record_class: OperationRecord)
+          super()
+          @record_class = record_class
+        end
+
+        def reserve(operation)
+          @record_class.transaction do
+            lock_actor!(operation.actor_id)
+            if @record_class.exists?(operation.id)
+              raise InvalidInput, "operation #{operation.id} is already reserved"
+            end
+
+            enforce_concurrency!(operation)
+            insert!(operation)
+          end
+        rescue ActiveRecord::RecordNotUnique
+          raise InvalidInput, "operation #{operation.id} is already reserved"
+        end
+
+        def attach_or_reserve(operation)
+          @record_class.transaction do
+            lock_actor!(operation.actor_id)
+            existing = find_by_idempotency_key(operation.actor_id, operation.run_id, operation.idempotency_key)
+            if existing
+              unless existing.request_digest == operation.request_digest
+                raise InvalidInput, "idempotency key belongs to a different request"
+              end
+              return existing.to_operation
+            end
+            raise InvalidInput, "operation is already reserved" if @record_class.exists?(operation.id)
+
+            enforce_concurrency!(operation)
+            insert!(operation)
+          end
+        end
+
+        def fetch(id)
+          @record_class.find_by(id: id)&.to_operation
+        end
+
+        def fetch!(id)
+          fetch(id) || raise(InvalidInput, "unknown operation #{id.inspect}")
+        end
+
+        # Claims the operation for one worker by bumping its fence token.
+        def lease(id, actor_id:, run_id:, now:)
+          @record_class.transaction do
+            record = locked!(id)
+            assert_actor!(record, actor_id, run_id)
+            if record.to_operation.terminal?
+              raise InvalidInput, "operation #{id} is already #{record.state}"
+            end
+
+            leased = record.to_operation.with_fence(record.fence + 1, now: now)
+            persist!(record, leased)
+          end
+        end
+
+        # Persists +operation+ only when its fence is current.
+        def update(operation)
+          @record_class.transaction do
+            record = locked!(operation.id)
+            operation.validate_update!(record.to_operation)
+            persist!(record, operation)
+          end
+        end
+
+        def claim_start(operation, now:)
+          @record_class.transaction do
+            record = locked!(operation.id)
+            current = record.to_operation
+            operation.validate_update!(current)
+            raise InvalidInput, "operation was already started" unless current.state == :reserved
+            raise BudgetExhausted, "operation wall-clock budget exhausted" if current.expired?(now)
+
+            persist!(record, current.advance(:starting, now: now))
+          end
+        end
+
+        def record_session(operation, session_id:, now:)
+          @record_class.transaction do
+            record = locked!(operation.id)
+            assert_actor!(record, operation.actor_id, operation.run_id)
+            current = record.to_operation
+            if current.session_id && current.session_id != session_id
+              raise InvalidInput, "operation session cannot change"
+            end
+            target = current.fence == operation.fence ? :active : :cleanup_pending
+            persist!(record, current.advance(target, session_id: session_id, now: now))
+          end
+        end
+
+        def confirm_closed(operation, session_id:, now:)
+          @record_class.transaction do
+            record = locked!(operation.id)
+            assert_actor!(record, operation.actor_id, operation.run_id)
+            current = record.to_operation
+            raise InvalidInput, "operation session cannot change" unless current.session_id == session_id
+
+            target = current.cancel_requested? ? :cancelled : :closed
+            persist!(record, current.advance(target, now: now))
+          end
+        end
+
+        def mark_cleanup_pending(id, actor_id:, run_id:, error_code: nil, now:)
+          @record_class.transaction do
+            record = locked!(id)
+            assert_actor!(record, actor_id, run_id)
+            updated = record.to_operation.advance(:cleanup_pending, now: now, error_code: error_code)
+            persist!(record, updated)
+          end
+        end
+
+        # Host-initiated cancellation. Marks the operation and fences stale workers.
+        #
+        # @return [Operation] the cancelled (or already terminal) operation
+        def cancel(id, actor_id:, run_id:, now:)
+          @record_class.transaction do
+            record = locked!(id)
+            assert_actor!(record, actor_id, run_id)
+            current = record.to_operation
+            return current if current.terminal? || current.cancel_requested?
+
+            cancelled = current.with_fence(record.fence + 1, now: now).request_cancel(now: now)
+            persist!(record, cancelled)
+          end
+        end
+
+        def open_for(actor_id)
+          @record_class.where(actor_id: actor_id).where(state: open_states).order(:created_at).map(&:to_operation)
+        end
+
+        def open_operations
+          @record_class.where(state: open_states).order(:created_at).map(&:to_operation)
+        end
+
+        # Finds an existing operation by its actor/run idempotency key.
+        def find_by_idempotency_key(actor_id, run_id, key)
+          return nil if key.nil?
+
+          @record_class.find_by(actor_id: actor_id, run_id: run_id, idempotency_key: key)
+        end
+
+        private
+
+        def locked!(id)
+          # SQLite ignores SELECT FOR UPDATE. Acquire its write lock before reading
+          # so a second worker cannot read the old state and later overwrite it.
+          if @record_class.connection.adapter_name == "SQLite"
+            @record_class.where(id: id).update_all("fence = fence")
+          end
+          @record_class.lock.find_by(id: id) || raise(InvalidInput, "unknown operation #{id.inspect}")
+        end
+
+        def open_states = Operation::OPEN_STATES.map(&:to_s)
+
+        # The first statement acquires SQLite's write lock before any reads. On
+        # PostgreSQL both statements serialize on the same primary-key row.
+        def lock_actor!(actor_id)
+          unless %w[SQLite PostgreSQL].include?(@record_class.connection.adapter_name)
+            raise UnsupportedSecurityCapability, "durable store supports SQLite and PostgreSQL only"
+          end
+          ActorRecord.insert_all([ { id: actor_id, sequence: 0 } ], unique_by: :id)
+          ActorRecord.where(id: actor_id).update_all("sequence = sequence + 1")
+        end
+
+        def enforce_concurrency!(operation)
+          open = @record_class.where(actor_id: operation.actor_id).where(state: open_states).count
+          return if open < operation.budget.max_concurrent
+
+          raise BudgetExhausted,
+                "actor #{operation.actor_id.inspect} already holds #{open} open browser operation(s)"
+        end
+
+        def assert_actor!(record, actor_id, run_id)
+          return if record.actor_id == actor_id && record.run_id == run_id
+
+          raise NotAuthorized, "operation #{record.id} belongs to a different actor or run"
+        end
+
+        def insert!(operation)
+          record = @record_class.new(id: operation.id)
+          persist!(record, operation)
+          # Databases persist timestamps at their configured precision. Return that
+          # canonical identity rather than a nanosecond value that cannot round-trip.
+          record.reload.to_operation
+        end
+
+        def persist!(record, operation)
+          record.actor_id = operation.actor_id
+          record.run_id = operation.run_id
+          record.state = operation.state.to_s
+          record.session_id = operation.session_id
+          record.idempotency_key = operation.idempotency_key
+          record.request_digest = operation.request_digest
+          record.steps = operation.steps
+          record.bytes = operation.bytes
+          record.fence = operation.fence
+          record.error_code = operation.error_code
+          record.cancel_requested = operation.cancel_requested?
+          record.budget = @record_class.dump_budget(operation.budget)
+          record.created_at = operation.created_at
+          record.updated_at = operation.updated_at
+          record.save!
+          operation
+        end
+      end
+    end
+  end
+end