search-engine-for-typesense 30.1.8.3 → 30.1.8.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33213d7f97f8014582dc5495606a158d61f8cd72c71d7467c5c98b8b4d5bced3
-  data.tar.gz: 766b1c9e8dfe3e20ad57c32ddfc5a0d3ca2c5fb6dba763f4585f5c27fd461d8f
+  metadata.gz: d6c07978f5cb0d447f674050793a5d30541d112c98bd51992463aea103134273
+  data.tar.gz: 2807c15e8ac558a8f519c4af880c6da14d31442ea1921778c0ec267c166c0423
 SHA512:
-  metadata.gz: 60603142ea1d344165fe4bf395eb7c395775bd76697247aa8fc79d3a153adb8ffe95f5a2e7a0df0fcd61f39ebe7f8fbcb17077b06752f2aad1a97d91b2bade03
-  data.tar.gz: 505aa6f7cec4aeb51ce7be0b3985ea479679c578ee401e24415a4f32d77ccfb965c95fb95f649daf293d32a41523458bb44d99eec32387f054017a67e507ffd3
+  metadata.gz: 0f268f7adae79d3899a7c8cabcb7556fdd03442391d3c64c51f15e915ac78f7813719fa45030e280d566c56a05a5238e1e3e80a576ce6c2904bad85fcd000f71
+  data.tar.gz: 3499f0867134fdd0bfe2180c2e29ee81be40ed3c49db0c68b154be9c84166ae0388fa3fcc95e627fc3279ce1c79307ebe0385d022b2f24192fe694571cdfb0fc

data/README.md

@@ -188,6 +188,160 @@ Use a shared `Rails.cache` backend, or provide `c.indexer.partition_run_store`,
 the parent indexing process can see the same run metadata. Size the queue carefully: worker concurrency
 multiplies with any per-partition `max_parallel` setting.
 
+## PostgreSQL outbox sync
+
+Rails callbacks are convenient for ordinary `create`, `update`, and `destroy` flows, but they do not see
+every database write. Bulk SQL imports, database triggers, background functions, and direct maintenance
+scripts can change source tables without instantiating Active Record models. PostgreSQL outbox sync captures
+those writes at the database layer and lets the gem process them through ActiveJob.
+
+The flow is:
+
+1. A row-level PostgreSQL trigger writes a durable outbox row in the same transaction as the source table
+   change.
+2. The trigger calls `pg_notify` as a low-latency nudge after commit.
+3. A host-managed listener receives notifications, or falls back to polling, and enqueues
+   `SearchEngine::PostgresOutbox::DrainJob`.
+4. The drainer claims pending rows, coalesces older rows for the same collection/document pair, orders
+   collection groups with the dependency planner, and processes the resulting upserts/deletes.
+
+`pg_notify` is not durable. Treat notifications only as a wakeup signal; the outbox table is the source of
+truth. Run the listener in a process lifecycle you control, and keep fallback polling enabled so missed
+notifications are drained later.
+
+PostgreSQL outbox sync is disabled by default:
+
+```ruby
+# config/initializers/search_engine.rb
+SearchEngine.configure do |c|
+  c.postgres_outbox.enabled = true
+  c.postgres_outbox.listener_enabled = -> { Rails.env.production? }
+  c.postgres_outbox.table_name = "search_engine_outbox_events"
+  c.postgres_outbox.channel = "search_engine_outbox"
+  c.postgres_outbox.queue_name = "search_engine"
+  c.postgres_outbox.batch_size = 1000
+  c.postgres_outbox.poll_interval_s = 5
+  c.postgres_outbox.retention_s = 7.days.to_i
+
+  # Optional. Leave off when your deployment already guarantees one listener.
+  c.postgres_outbox.advisory_lock = false
+end
+```
+
+Generate and edit the migrations:
+
+```bash
+bin/rails generate search_engine:postgres_outbox:install
+```
+
+The events table migration should include the gem helper:
+
+```ruby
+class CreateSearchEngineOutboxEvents < ActiveRecord::Migration[7.1]
+  include SearchEngine::PostgresOutbox::MigrationHelpers
+
+  def change
+    create_search_engine_outbox_events
+  end
+end
+```
+
+Add one trigger per source table that should write outbox events:
+
+```ruby
+class AddSearchEngineOutboxTriggers < ActiveRecord::Migration[7.1]
+  include SearchEngine::PostgresOutbox::MigrationHelpers
+
+  def up
+    create_search_engine_outbox_trigger(
+      :products,
+      source_model: "Product",
+      collection: "products"
+    )
+
+    create_search_engine_outbox_trigger(
+      :product_variants,
+      source_model: "ProductVariant",
+      collection: "product_variants",
+      record_id_sql: "record_data.id::text",
+      document_id_sql: "record_data.product_id::text || '-' || record_data.id::text"
+    )
+  end
+
+  def down
+    drop_search_engine_outbox_trigger(:product_variants)
+    drop_search_engine_outbox_trigger(:products)
+  end
+end
+```
+
+`record_id_sql` and `document_id_sql` are trusted migration SQL expressions. They may refer to the
+PL/pgSQL `record_data` variable, which is `NEW` for inserts/updates and `OLD` for deletes.
+
+Pair triggered source models with `sync_strategy: :postgres_outbox` so Active Record callbacks do not also
+write to Typesense for the same changes:
+
+```ruby
+class Product < ApplicationRecord
+  include SearchEngine::ActiveRecordSyncable
+
+  search_engine_syncable collection: :products, sync_strategy: :postgres_outbox
+end
+```
+
+The listener lifecycle belongs to the host app. This Sidekiq initializer is one example; any process manager
+or ActiveJob backend can start and stop a listener as long as it can enqueue jobs:
+
+```ruby
+# config/initializers/search_engine_outbox_listener.rb
+if defined?(Sidekiq)
+  Sidekiq.configure_server do |config|
+    listener = nil
+
+    config.on(:startup) do
+      outbox = SearchEngine.config.postgres_outbox
+      next unless outbox.enabled && outbox.listener_enabled.call
+
+      listener = SearchEngine::PostgresOutbox::Listener.new.start
+    end
+
+    config.on(:quiet) { listener&.stop(timeout: 5) }
+    config.on(:shutdown) { listener&.stop(timeout: 5) }
+  end
+end
+```
+
+Custom processors can override the default collection handling. Register processors by collection name and
+return `SearchEngine::PostgresOutbox::ProcessorResult`:
+
+```ruby
+SearchEngine.configure do |c|
+  c.postgres_outbox.collection_processors["products"] = lambda do |events:, context:|
+    document_ids = events.map(&:document_id)
+    ProductSearchSync.call(document_ids: document_ids, worker_id: context[:worker_id])
+
+    SearchEngine::PostgresOutbox::ProcessorResult.success(events.map(&:id))
+  rescue StandardError => error
+    SearchEngine::PostgresOutbox::ProcessorResult.failure(events.map(&:id), error: error)
+  end
+end
+```
+
+When one collection references another, declare those references on the SearchEngine models. The outbox
+drainer uses the same dependency planner direction as bulk cascade planning, so parent/source collections
+are processed before dependent collections in the same drain pass. If a collection group fails, later
+dependent groups are left retryable instead of being processed against stale data.
+
+Enable `c.postgres_outbox.advisory_lock = true` when multiple processes may start listeners and your host
+deployment cannot guarantee exactly one listener. The listener uses `pg_try_advisory_lock` with
+`c.postgres_outbox.advisory_lock_key`, or a stable key derived from the notification channel. If the lock is
+not acquired, that listener sleeps and retries.
+
+Processed and superseded rows are safe to delete after your retention window. Failed rows should be
+inspected before deletion because they contain the last error and retry state. A typical cleanup job deletes
+only rows with `status IN ('processed', 'superseded')` and `processed_at` older than
+`c.postgres_outbox.retention_s`.
+
 ## Example app
 
 See `examples/demo_shop` — demonstrates single/multi search, JOINs, grouping, presets/curation, and DX/observability. Supports offline mode via the stub client (see [Testing](https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/testing)).

data/app/search_engine/search_engine/postgres_outbox/drain_job.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module SearchEngine
+  module PostgresOutbox
+    # ActiveJob entrypoint for one bounded PostgreSQL outbox drain pass.
+    class DrainJob < ::ActiveJob::Base
+      queue_as do
+        SearchEngine.config.postgres_outbox.queue_name.to_s
+      end
+
+      # Drain pending outbox events once when PostgreSQL outbox processing is enabled.
+      # @param limit [Integer, nil] optional maximum number of events to claim
+      # @return [Hash, nil]
+      def perform(limit: nil)
+        return nil unless SearchEngine.config.postgres_outbox.enabled
+
+        drainer = SearchEngine::PostgresOutbox::Drainer.new
+        return drainer.drain_once if limit.nil?
+
+        drainer.drain_once(limit: limit)
+      end
+    end
+  end
+end

data/lib/generators/search_engine/postgres_outbox/install_generator.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/active_record'
+
+module SearchEngine
+  module Generators
+    module PostgresOutbox
+      # Install generator for PostgreSQL outbox migration helpers.
+      #
+      # @example
+      #   rails g search_engine:postgres_outbox:install
+      class InstallGenerator < Rails::Generators::Base
+        include ActiveRecord::Generators::Migration
+
+        source_root File.expand_path('templates', __dir__)
+
+        def create_outbox_table_migration
+          migration_template 'create_outbox_events.rb.tt',
+                             'db/migrate/create_search_engine_outbox_events.rb'
+        end
+
+        def create_trigger_examples_migration
+          migration_template 'add_outbox_triggers.rb.tt',
+                             'db/migrate/add_search_engine_outbox_triggers.rb'
+        end
+
+        def self.next_migration_number(_dirname)
+          sleep 1
+          Time.now.utc.strftime('%Y%m%d%H%M%S')
+        end
+      end
+    end
+  end
+end

data/lib/generators/search_engine/postgres_outbox/templates/add_outbox_triggers.rb.tt

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+class AddSearchEngineOutboxTriggers < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  include SearchEngine::PostgresOutbox::MigrationHelpers
+
+  def up
+    # Add one trigger per source table that should write SearchEngine outbox
+    # events. Triggers fire AFTER INSERT/UPDATE/DELETE by default, insert the
+    # outbox row in the same database transaction as the source change, and call
+    # pg_notify after commit as a non-durable wakeup nudge for the listener.
+    #
+    # Pair triggered source models with:
+    #   search_engine_syncable collection: :collection_name, sync_strategy: :postgres_outbox
+    # so Active Record callbacks do not also sync the same changes.
+    #
+    # record_id_sql and document_id_sql are trusted migration SQL expressions.
+    # They may reference record_data, which is NEW for inserts/updates and OLD
+    # for deletes.
+    #
+    # Simple id example:
+    # create_search_engine_outbox_trigger(
+    #   :products,
+    #   source_model: 'Product',
+    #   collection: 'products'
+    # )
+
+    # Custom document id example:
+    # create_search_engine_outbox_trigger(
+    #   :product_store_entries,
+    #   source_model: 'ProductStoreEntry',
+    #   collection: 'product_store_entries',
+    #   document_id_sql: "record_data.product_id::text || '-' || record_data.store_id::text"
+    # )
+  end
+
+  def down
+    # Drop triggers/functions in reverse order during rollback or teardown.
+    # drop_search_engine_outbox_trigger(:product_store_entries)
+    # drop_search_engine_outbox_trigger(:products)
+  end
+end

data/lib/generators/search_engine/postgres_outbox/templates/create_outbox_events.rb.tt

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class CreateSearchEngineOutboxEvents < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  include SearchEngine::PostgresOutbox::MigrationHelpers
+
+  def change
+    create_search_engine_outbox_events
+  end
+end

data/lib/search_engine/active_record_syncable.rb

@@ -5,8 +5,10 @@ require 'active_support/concern'
 module SearchEngine
   # ActiveRecord concern to keep a Typesense collection in sync.
   #
-  # Include into an AR model and call {.search_engine_syncable} to install
-  # lifecycle callbacks that upsert on create/update and delete on destroy.
+  # Include into an AR model and call {.search_engine_syncable} to store sync
+  # metadata. The default callback strategy installs lifecycle callbacks that
+  # upsert on create/update and delete on destroy; the postgres_outbox strategy
+  # stores metadata without installing callbacks.
   #
   # @example
   #   class Product < ApplicationRecord
@@ -21,6 +23,7 @@ module SearchEngine
       #
       # - collection: defaults to the AR class tableized name (snake_case, plural)
       # - on: one or many of :create, :update, :destroy (strings or symbols)
+      # - sync_strategy: :callbacks (default) or :postgres_outbox
       #
       # Validates that either a physical Typesense collection exists for the
       # given name or a SearchEngine model is registered for it. Mapping for
@@ -29,20 +32,23 @@ module SearchEngine
       #
       # @param collection [Symbol, String, nil]
       # @param on [Array<Symbol,String>, Symbol, String, nil]
+      # @param sync_strategy [Symbol, String, nil]
       # @return [Class] self (for macro chaining)
-      def search_engine_syncable(collection: nil, on: nil)
+      def search_engine_syncable(collection: nil, on: nil, sync_strategy: :callbacks)
         effective_actions = on
 
         cfg = SearchEngine::ActiveRecordSyncable.__normalize_config_for(
           self,
           collection: collection,
-          actions: effective_actions
+          actions: effective_actions,
+          sync_strategy: sync_strategy
         )
 
         # Store config on the AR class (used by instance methods)
         instance_variable_set(:@__se_syncable_cfg__, cfg)
 
-        SearchEngine::ActiveRecordSyncable.__register_callbacks_for(self, cfg)
+        SearchEngine::ActiveRecordSyncable.__register_callbacks_for(self, cfg) if cfg[:sync_strategy] == :callbacks
+
         self
       end
     end
@@ -177,12 +183,14 @@ module SearchEngine
     # @param ar_klass [Class]
     # @param collection [String,Symbol,nil]
     # @param actions [Array<String,Symbol>, String, Symbol, nil]
+    # @param sync_strategy [String, Symbol, nil]
     # @return [Hash]
-    def __normalize_config_for(ar_klass, collection:, actions:)
+    def __normalize_config_for(ar_klass, collection:, actions:, sync_strategy: :callbacks)
       require 'active_support/inflector'
 
       logical = (collection || ActiveSupport::Inflector.tableize(ar_klass.name)).to_s
       normalized_actions = __normalize_actions(actions)
+      normalized_sync_strategy = __normalize_sync_strategy(sync_strategy)
 
       # Best-effort resolve SearchEngine model now; fall back to lazy resolution
       se_klass = begin
@@ -200,6 +208,7 @@ module SearchEngine
       {
         logical: logical,
         actions: normalized_actions,
+        sync_strategy: normalized_sync_strategy,
         se_klass: se_klass
       }
     end
@@ -222,6 +231,20 @@ module SearchEngine
       list.uniq
     end
 
+    # @api private
+    # @param strategy [String, Symbol, nil]
+    # @return [Symbol]
+    def __normalize_sync_strategy(strategy)
+      allowed = %i[callbacks postgres_outbox]
+      normalized = strategy.nil? ? :callbacks : strategy.to_s.downcase.strip.to_sym
+
+      unless allowed.include?(normalized)
+        raise ArgumentError, "search_engine_syncable: sync_strategy must be within #{allowed.inspect}"
+      end
+
+      normalized
+    end
+
     # (no-op placeholder kept for backwards compatibility of method table in case of reloads)
 
     # @api private

data/lib/search_engine/bulk.rb

@@ -94,19 +94,9 @@ module SearchEngine
         # Fallback to all declared/registered collections when no explicit targets are given.
         input_names = SearchEngine::CollectionResolver.models_map.keys if input_names.empty?
 
-        reverse_graph = SearchEngine::Cascade.build_reverse_graph(client: ts_client)
-        input_set = input_names.to_h { |n| [n, true] }
-
-        # Identify inputs that are referrers of other inputs (skip them in stage 1)
-        internal_referrers = internal_referrers_within_inputs(reverse_graph, input_set)
-
-        stage1_list = input_names.reject { |n| internal_referrers.include?(n) }
-
-        # Collect unique referencers of any input for the final cascade step
-        cascade_candidates = unique_referencers_of_inputs(reverse_graph, input_names)
-
-        # Order cascade candidates among themselves by dependency (referenced first)
-        cascade_order = topo_sort_subset(reverse_graph, cascade_candidates)
+        stages = SearchEngine::DependencyPlanner.bulk_stages(input_names, source: :auto, client: ts_client)
+        stage1_list = stages[:stage_1]
+        cascade_order = stages[:cascade]
 
         stats = {
           inputs: input_names,
@@ -196,89 +186,6 @@ module SearchEngine
         filtered.uniq
       end
 
-      # Compute the subset of inputs that are referrers of other inputs.
-      # reverse_graph: target => [{ referrer, local_key, foreign_key }, ...]
-      # @param reverse_graph [Hash]
-      # @param input_set [Hash{String=>true}]
-      # @return [Set<String>]
-      def internal_referrers_within_inputs(reverse_graph, input_set)
-        require 'set'
-        refs = Set.new
-        reverse_graph.each do |target, edges|
-          next unless input_set[target]
-
-          Array(edges).each do |e|
-            r = (e[:referrer] || e['referrer']).to_s
-            refs.add(r) if input_set[r]
-          end
-        end
-        refs
-      end
-
-      # Unique list of referencers of any input logical name.
-      # @param reverse_graph [Hash]
-      # @param inputs [Array<String>]
-      # @return [Array<String>]
-      def unique_referencers_of_inputs(reverse_graph, inputs)
-        require 'set'
-        seen = Set.new
-        Array(inputs).each do |name|
-          Array(reverse_graph[name]).each do |e|
-            r = (e[:referrer] || e['referrer']).to_s
-            seen.add(r) unless r.strip.empty?
-          end
-        end
-        seen.to_a
-      end
-
-      # Topologically sort a subset of nodes using reverse_graph edges.
-      # Nodes are referencers; for any edge referrer -> target, ensure target comes first when it is in the subset.
-      # @param reverse_graph [Hash]
-      # @param subset [Array<String>]
-      # @return [Array<String>]
-      def topo_sort_subset(reverse_graph, subset)
-        require 'set'
-        nodes = Array(subset).uniq
-        node_set = nodes.to_h { |n| [n, true] }
-
-        # Build forward adjacency among subset nodes and indegree counts
-        adj = Hash.new { |h, k| h[k] = Set.new }
-        indeg = Hash.new(0)
-
-        nodes.each { |n| indeg[n] = 0 }
-
-        reverse_graph.each do |target, edges|
-          Array(edges).each do |e|
-            ref = (e[:referrer] || e['referrer']).to_s
-            tgt = target.to_s
-            next unless node_set[ref] && node_set[tgt]
-
-            # referrer depends on target: target should precede referrer
-            unless adj[tgt].include?(ref)
-              adj[tgt] << ref
-              indeg[ref] += 1
-            end
-          end
-        end
-
-        # Kahn's algorithm (stable by name)
-        queue = nodes.select { |n| indeg[n].to_i <= 0 }.sort
-        order = []
-        until queue.empty?
-          n = queue.shift
-          order << n
-          adj[n].each do |m|
-            indeg[m] -= 1
-            queue << m if indeg[m] <= 0
-          end
-          queue.sort!
-        end
-
-        # Append any remaining nodes (cycles) in stable name order
-        remaining = nodes - order
-        order + remaining.sort
-      end
-
       # Resolve a collection model class from a collection name.
       # Uses CollectionResolver for better fallback logic and model discovery.
       # @param name [String]

data/lib/search_engine/config.rb

@@ -264,6 +264,58 @@ module SearchEngine
       end
     end
 
+    # Lightweight nested configuration for PostgreSQL outbox sync.
+    class PostgresOutboxConfig
+      # @return [Boolean] global kill switch for PostgreSQL outbox sync
+      attr_accessor :enabled
+      # @return [String] database table used by host-managed outbox events
+      attr_accessor :table_name
+      # @return [String] PostgreSQL notification channel for wakeups
+      attr_accessor :channel
+      # @return [String] queue name used by host app job dispatch
+      attr_accessor :queue_name
+      # @return [Integer] maximum events to claim per processing batch
+      attr_accessor :batch_size
+      # @return [Integer] maximum processing attempts before leaving an event failed
+      attr_accessor :max_attempts
+      # @return [Integer] polling interval in seconds
+      attr_accessor :poll_interval_s
+      # @return [Integer] listener wait timeout in seconds
+      attr_accessor :listener_wait_timeout_s
+      # @return [Integer] processing timeout in seconds
+      attr_accessor :processing_timeout_s
+      # @return [Integer] retention period in seconds
+      attr_accessor :retention_s
+      # @return [Boolean] whether host processing should use advisory locking
+      attr_accessor :advisory_lock
+      # @return [Integer, nil] optional PostgreSQL advisory lock key
+      attr_accessor :advisory_lock_key
+      # @return [#call] predicate controlling whether listener work may run
+      attr_accessor :listener_enabled
+      # @return [Hash] host-provided collection processors by collection name
+      attr_accessor :collection_processors
+      # @return [#call] retry backoff calculator receiving the attempt number
+      attr_accessor :retry_backoff
+
+      def initialize
+        @enabled = false
+        @table_name = 'search_engine_outbox_events'
+        @channel = 'search_engine_outbox'
+        @queue_name = 'search_engine'
+        @batch_size = 1000
+        @max_attempts = 10
+        @poll_interval_s = 5
+        @listener_wait_timeout_s = 30
+        @processing_timeout_s = 900
+        @retention_s = 604_800
+        @advisory_lock = false
+        @advisory_lock_key = nil
+        @listener_enabled = -> { false }
+        @collection_processors = {}
+        @retry_backoff = ->(attempt) { [attempt.to_i, 1].max * 5 }
+      end
+    end
+
     # Lightweight nested configuration for observability/logging.
     # Kept for backward compatibility during refactor; delegates to external class.
     #
@@ -414,6 +466,7 @@ module SearchEngine
       @mapper = MapperConfig.new
       @partitioning = PartitioningConfig.new
       @stale_deletes = StaleDeletesConfig.new
+      @postgres_outbox = PostgresOutboxConfig.new
       @observability = ObservabilityConfig.new
       @grouping = GroupingConfig.new
       @selection = SelectionConfig.new
@@ -525,6 +578,12 @@ module SearchEngine
       @stale_deletes ||= StaleDeletesConfig.new
     end
 
+    # Expose PostgreSQL outbox configuration.
+    # @return [SearchEngine::Config::PostgresOutboxConfig]
+    def postgres_outbox
+      @postgres_outbox ||= PostgresOutboxConfig.new
+    end
+
     # Expose structured logging configuration.
     #
     # By default `mode` is nil which disables the structured `LoggingSubscriber`.
@@ -722,6 +781,7 @@ module SearchEngine
         sources: sources_hash_for_to_h,
         mapper: mapper_hash_for_to_h,
         partitioning: partitioning_hash_for_to_h,
+        postgres_outbox: postgres_outbox_hash_for_to_h,
         observability: observability_hash_for_to_h,
         selection: selection_hash_for_to_h,
         presets: presets_hash_for_to_h,
@@ -799,6 +859,26 @@ module SearchEngine
       }
     end
 
+    def postgres_outbox_hash_for_to_h
+      {
+        enabled: postgres_outbox.enabled ? true : false,
+        table_name: postgres_outbox.table_name,
+        channel: postgres_outbox.channel,
+        queue_name: postgres_outbox.queue_name,
+        batch_size: postgres_outbox.batch_size,
+        max_attempts: postgres_outbox.max_attempts,
+        poll_interval_s: postgres_outbox.poll_interval_s,
+        listener_wait_timeout_s: postgres_outbox.listener_wait_timeout_s,
+        processing_timeout_s: postgres_outbox.processing_timeout_s,
+        retention_s: postgres_outbox.retention_s,
+        advisory_lock: postgres_outbox.advisory_lock ? true : false,
+        advisory_lock_key: postgres_outbox.advisory_lock_key,
+        listener_enabled: postgres_outbox.listener_enabled,
+        collection_processors: postgres_outbox.collection_processors,
+        retry_backoff: postgres_outbox.retry_backoff
+      }
+    end
+
     def observability_hash_for_to_h
       {
         enabled: observability.enabled ? true : false,