spree_core 5.6.1 → 6.0.0.beta1

data/lib/spree/reporting/registry.rb

@@ -0,0 +1,294 @@
+module Spree
+  module Reporting
+    # A metric aggregates rows into one number.
+    #
+    # @!attribute sql
+    #   Portable aggregate SQL fragment (no DB-specific functions).
+    # @!attribute base
+    #   Root relation the aggregate runs against (:orders or :line_items).
+    # @!attribute format
+    #   :money | :integer | :decimal | :percent — :money metrics force a
+    #   single-currency scope; :percent metrics arrive as the number a merchant
+    #   reads (42.5), not the fraction.
+    # @!attribute ratio
+    #   Derived metrics: [numerator_metric, denominator_metric], computed
+    #   post-aggregation per row and for totals.
+    # @!attribute subject
+    #   Callable returning the model class a caller must be able to read for
+    #   this number — for a metric that exposes money outside the order itself,
+    #   like the marketplace's commission. Declared with key_scope.
+    # @!attribute key_scope
+    #   API-key scope the same number requires.
+    # @!attribute requires_grouping
+    #   Dimension name this metric is only meaningful grouped by (e.g.
+    #   :customer for a lifetime figure). Ungrouped it is refused, and it
+    #   publishes no dimensionless total.
+    # @!attribute grouped_sql
+    #   Optional aggregate used only for the grouped query, where dimension
+    #   joins are present. See #sql_for.
+    # @!attribute suggests
+    #   Metric to reach for instead when this one is refused for a breakdown
+    #   it cannot answer — named in the error so a caller learns the
+    #   vocabulary from the refusal rather than by trial.
+    Metric = Struct.new(:name, :sql, :base, :format, :ratio, :subject, :key_scope,
+                        :requires_grouping, :suggests, :grouped_sql, keyword_init: true) do
+      # The aggregate to use when the query carries its dimension joins. A
+      # metric whose money lives on a joined row reads it directly there, and
+      # falls back to `sql` for the dimensionless total, which has no joins.
+      def sql_for(grouped:) = (grouped && grouped_sql.presence) || sql
+
+      def derived? = ratio.present?
+
+      # The dimension this metric only means anything inside of. A customer's
+      # lifetime value is not a figure the whole store has, so a query that
+      # does not group by that dimension is refused and the dimensionless
+      # total is suppressed rather than rendered as a headline.
+      def per_group? = requires_grouping.present?
+      def money? = format == :money
+    end
+
+    # A dimension groups rows. The definition owns every behavior keyed off
+    # it, so an extension-registered dimension works end-to-end (filtering,
+    # hydration, authorization) without touching core.
+    #
+    # @!attribute base
+    #   The finest base able to express this grouping (:orders groupings are
+    #   also reachable from :line_items via the order join; not vice versa).
+    # @!attribute column
+    #   Group-by column (symbol on the base table, or a table-qualified string).
+    # @!attribute joins
+    #   Extra association joins the grouping needs (from the base relation).
+    # @!attribute type
+    #   :value | :time — :time dimensions take a grain and zero-fill buckets.
+    # @!attribute lookup
+    #   Schema tag naming what the dimension's keys identify (e.g. :product) —
+    #   set alongside +hydrate+ so clients know display payloads are coming.
+    # @!attribute resolve
+    #   ->(store, value) resolving filter values (prefixed ids) to raw keys,
+    #   always through store-scoped collections. Omitted = values pass through.
+    # @!attribute hydrate
+    #   ->(store, keys, params) returning { raw_key => { id:, label:, meta: } }
+    #   display payloads for the API layer. Omitted = raw keys on the wire.
+    # @!attribute subject
+    #   -> { SomeClass } authorization subject. JWT admin sessions must be
+    #   able to `:read` the class to reference the member; order data itself
+    #   is covered by the base Spree::Order check. Lazy so registration never
+    #   autoloads models.
+    # @!attribute key_scope
+    #   API-key scope (e.g. 'read_products') required alongside `read_reports`
+    #   for secret keys to reference the member. Mandatory whenever `subject`
+    #   is declared, so key access is decided at registration, never skipped.
+    # @!attribute values
+    #   Enumerable raw values for status-like dimensions (an Array, or a lambda
+    #   returning one so model constants load lazily). Published in the schema
+    #   as the filter value list.
+    # @!attribute population
+    #   Lambda (store) -> relation enumerating every record the dimension can
+    #   group by. Declared rather than inferred from `lookup`, because it is
+    #   what `include_empty` reads to produce rows for members with no
+    #   matching facts ("which products never sold"); a dimension without one
+    #   refuses `include_empty` instead of quietly returning only what sold.
+    Dimension = Struct.new(:name, :base, :column, :expression, :joins, :type, :grains, :lookup,
+                           :resolve, :hydrate, :subject, :key_scope, :values, :population, keyword_init: true) do
+      def time? = type == :time
+
+      def population? = population.present?
+
+      # A dimension whose key is computed rather than read from a column. The
+      # compiler validates `column` down to `table.column` so registration
+      # cannot smuggle SQL by accident; `expression` is how a developer says
+      # the SQL is deliberate, and it carries the same trust as a metric's.
+      def expression? = expression.present?
+
+      def enumerated_values
+        values.respond_to?(:call) ? values.call : values
+      end
+    end
+
+    # A relation metrics aggregate over, and the family it belongs to.
+    #
+    # Bases exist because the things a store measures sit at different grains:
+    # an order has no payment method, a payment has no line items, a stock
+    # movement has neither a customer nor a currency. A base names one grain,
+    # says how to reach it store-scoped, and declares which family it can be
+    # queried alongside.
+    #
+    # @!attribute family
+    #   Bases sharing a family combine in one query (:orders and :line_items
+    #   both answer questions about sales). Bases in different families never
+    #   do — the query refuses the mix rather than inventing a join between
+    #   grains that have no honest relationship.
+    # @!attribute relation
+    #   ->(store, range, currency) returning the store-scoped, range-filtered
+    #   relation. Money bases filter the currency; countable ones ignore it.
+    # @!attribute table
+    #   The base's own table, as a %{placeholder}. Where a bare `column:`
+    #   symbol on one of its dimensions is read from. Deliberately separate
+    #   from time_column: a line item's clock lives on its order.
+    # @!attribute time_column
+    #   Table-qualified column the range filters on, named in the schema so a
+    #   caller knows what "last 30 days" means for this base.
+    # @!attribute reaches
+    #   Bases whose dimensions this one can group by, itself included. An
+    #   :orders dimension is reachable from :line_items through the order join;
+    #   not the reverse.
+    # @!attribute clock
+    #   What this base's time column means, in a merchant's words ("anchored
+    #   on when the order completed"). Named in the cross-family refusal so a
+    #   caller can see why two metrics cannot share a row.
+    Base = Struct.new(:name, :family, :table, :relation, :time_column, :reaches, :clock, keyword_init: true) do
+      def reaches?(dimension_base) = reaches.key?(dimension_base)
+
+      # The association a dimension on `dimension_base` is joined through from
+      # here — nil when it is this base's own, so the join needs no hop.
+      def path_to(dimension_base) = reaches[dimension_base]
+    end
+
+    # A point-in-time count of things that need attention right now: orders
+    # waiting to ship, returns waiting on a decision, variants running low.
+    # No time range, no currency and no base — a counter is not a report
+    # over a period but the state of the store at this instant, which is why
+    # it is evaluated by a lambda rather than compiled into the query.
+    #
+    # @!attribute count
+    #   ->(store, channel:) returning an Integer. A channel narrows what can
+    #   be narrowed (orders); store-wide facts such as stock ignore it.
+    # @!attribute subject / key_scope
+    #   Authorization, declared the same way as on metrics and dimensions,
+    #   so a caller sees only the counters over data they may read.
+    # @!attribute link
+    #   Where the number leads, declared beside the count so the two cannot
+    #   disagree: `{ resource: 'orders', filters: [{ field:, operator:, value: }] }`.
+    #   Omitted when no list can honestly show exactly what was counted.
+    # @!attribute nav
+    #   Key of the sidebar entry this count badges, when it badges one. The
+    #   dashboard reads it rather than mapping counter names to nav entries
+    #   itself, so an extension's counter can badge its own nav entry without
+    #   a dashboard release.
+    Counter = Struct.new(:name, :count, :subject, :key_scope, :link, :nav, keyword_init: true)
+
+    # Allowlist of queryable metrics, dimensions and counters. One global
+    # instance lives at `Spree.reporting`; core seeds the starter vocabulary in
+    # the engine initializer and applications/extensions append theirs in
+    # initializer files.
+    class Registry
+      attr_reader :metrics, :dimensions, :bases, :counters
+
+      def initialize
+        @metrics = {}
+        @dimensions = {}
+        @bases = {}
+        @counters = {}
+      end
+
+      # @param name [Symbol]
+      # @param family [Symbol] bases sharing a family combine in one query
+      # @param table [String] the base's own table as a %{placeholder}
+      # @param relation [Proc] ->(store, range, currency) → store-scoped relation
+      # @param time_column [String] table-qualified column the range filters on
+      # @param reaches [Array<Symbol>] bases whose dimensions this one can group by
+      # @param reaches [Hash, Array, nil] bases whose dimensions this one can
+      #   group by, mapped to the association they are reached through (nil for
+      #   its own). An Array is read as "reachable, on this base's own table".
+      def base(name, replace: false, family:, table:, relation:, time_column:, reaches: nil, clock: nil)
+        name = name.to_sym
+        raise ArgumentError, "base #{name} already registered (pass replace: true to override)" if @bases.key?(name) && !replace
+
+        @bases[name] = Base.new(name: name, family: family, table: table, relation: relation,
+                                time_column: time_column, reaches: normalize_reaches(name, reaches),
+                                clock: clock)
+      end
+
+      def normalize_reaches(name, reaches)
+        return { name => nil } if reaches.nil?
+        return reaches.to_h { |base_name| [base_name, nil] } if reaches.is_a?(Array)
+
+        reaches
+      end
+
+      def base!(name)
+        @bases[name.to_sym] || raise(UnknownMember.new(:base, name, @bases.keys))
+      end
+
+      def metric(name, replace: false, **opts)
+        name = name.to_sym
+        raise ArgumentError, "metric #{name} already registered (pass replace: true to override)" if @metrics.key?(name) && !replace
+        if opts[:subject] && opts[:key_scope].blank?
+          raise ArgumentError, "metric #{name} declares a subject and must also declare its key_scope"
+        end
+
+        opts[:format] ||= :integer
+        @metrics[name] = Metric.new(name: name, **opts)
+      end
+
+      def dimension(name, replace: false, **opts)
+        name = name.to_sym
+        raise ArgumentError, "dimension #{name} already registered (pass replace: true to override)" if @dimensions.key?(name) && !replace
+        if opts[:subject] && opts[:key_scope].blank?
+          raise ArgumentError, "dimension #{name} declares a subject and must also declare its key_scope"
+        end
+
+        if opts[:column].blank? && opts[:expression].blank?
+          raise ArgumentError, "dimension #{name} needs a column or an expression"
+        end
+
+        if opts[:population] && !opts[:population].respond_to?(:call)
+          raise ArgumentError, "dimension #{name} needs a callable population"
+        end
+
+        opts[:type] ||= :value
+        @dimensions[name] = Dimension.new(name: name, **opts)
+      end
+
+      # @param name [Symbol]
+      # @param count [Proc] ->(store, channel:) → Integer
+      # @param link [Hash, nil] `{ resource:, filters: [{ field:, operator:, value: }] }`
+      # @param nav [String, nil] sidebar entry key this count badges
+      def counter(name, replace: false, count:, subject: nil, key_scope: nil, link: nil, nav: nil)
+        name = name.to_sym
+        raise ArgumentError, "counter #{name} already registered (pass replace: true to override)" if @counters.key?(name) && !replace
+        raise ArgumentError, "counter #{name} declares a subject and must also declare its key_scope" if subject && key_scope.blank?
+        raise ArgumentError, "counter #{name} needs a callable count" unless count.respond_to?(:call)
+
+        @counters[name] = Counter.new(name: name, count: count, subject: subject, key_scope: key_scope,
+                                      link: link, nav: nav)
+      end
+
+      def metric!(name)
+        @metrics[name.to_sym] || raise(UnknownMember.new(:metric, name, @metrics.keys))
+      end
+
+      def counter!(name)
+        @counters[name.to_sym] || raise(UnknownMember.new(:counter, name, @counters.keys))
+      end
+
+      def dimension!(name)
+        @dimensions[name.to_sym] || raise(UnknownMember.new(:dimension, name, @dimensions.keys))
+      end
+
+      # Whether a metric can be grouped or filtered by a dimension: every
+      # aggregated component of the metric must sit on a base that reaches the
+      # dimension's base. Order totals per product would double count, so
+      # :orders does not reach :line_items; the reverse holds through the order
+      # join. The single rule the schema and the compiler share.
+      #
+      # @param metric [Metric]
+      # @param dimension [Dimension]
+      # @return [Boolean]
+      def compatible?(metric, dimension)
+        components(metric).all? { |component| base!(component.base).reaches?(dimension.base) }
+      end
+
+      # A derived metric aggregates nothing itself — its components do.
+      def components(metric)
+        metric.derived? ? metric.ratio.map { |name| metric!(name) } : [metric]
+      end
+
+      # The family a metric belongs to, read through its components so a
+      # derived metric answers with its ingredients' family rather than nil.
+      def family_of(metric)
+        base!(components(metric).first.base).family
+      end
+    end
+  end
+end

data/lib/spree/reporting/result.rb

@@ -0,0 +1,10 @@
+module Spree
+  module Reporting
+    # Adapter output. All values are numeric (BigDecimal/Integer) — display
+    # formatting is the API layer's job.
+    #
+    # totals: { metric_name => { value:, previous:, growth: } }
+    # rows:   [ { dimensions: { dim_name => raw_key }, metrics: { metric_name => { value:, previous:, growth: } } } ]
+    Result = Struct.new(:meta, :totals, :rows, keyword_init: true)
+  end
+end

data/lib/spree/reporting/schema.rb

@@ -0,0 +1,124 @@
+module Spree
+  module Reporting
+    # The self-describing contract for one caller: labels and descriptions
+    # (localized), metric formats with the store currency, per-dimension
+    # metric compatibility, filter ops and enumerated values, the time-range
+    # grammar, and store meta — filtered to the members the caller may
+    # reference, so pickers never offer and agents never propose a member that
+    # would be refused. Drives `GET /reporting/schema` and the agent tool schema.
+    class Schema
+      # @param store [Spree::Store]
+      # @param registry [Registry]
+      # @param allowed [Proc] ->(member) { true/false } — permission gate,
+      #   asked about metrics and dimensions alike
+      def initialize(store:, registry: Spree.reporting, allowed: ->(_member) { true })
+        @store = store
+        @registry = registry
+        @allowed = allowed
+      end
+
+      def to_h
+        metrics = @registry.metrics.values.select { |m| @allowed.call(m) }
+        dimensions = @registry.dimensions.values.select { |d| @allowed.call(d) }
+        {
+          meta: {
+            currency: @store.default_currency,
+            timezone: (Time.find_zone(@store.preferred_timezone) || Time.zone).name,
+            supported_currencies: @store.supported_currencies_list.map(&:iso_code)
+          },
+          # Published so a builder can group the pickers and never offer a
+          # cross-family pair the query would refuse.
+          families: families(metrics),
+          metrics: metrics.map { |m| metric_entry(m) },
+          dimensions: dimensions.map { |d| dimension_entry(d, metrics) },
+          time_range: {
+            presets: (Query::PRESETS + Query::RELATIVE_PRESETS).map { |p| { name: p, label: translate('presets', p, :label) } },
+            relative: %w[last_<n>_days last_<n>_weeks last_<n>_months],
+            absolute: 'ISO 8601 dates or datetimes in `since` / `until`, resolved in the store timezone'
+          },
+          # Ranking defaults the compiler applies, published so a client never
+          # has to mirror them.
+          limits: { default: Query::DEFAULT_VALUE_LIMIT, max: Query::MAX_LIMIT,
+                    max_buckets: Query::MAX_BUCKETS },
+          # Filtering on an aggregate (HAVING) is a separate contract key from
+          # `filters`, which narrow on dimensions before aggregation.
+          metric_filter_ops: Query::METRIC_FILTER_OPS,
+          compare_modes: Query::COMPARE_MODES
+        }
+      end
+
+      # @param group [Symbol] :metrics | :dimensions
+      # @return [String] localized label (humanized name when none registered)
+      def label_for(group, name)
+        translate(group, name, :label)
+      end
+
+      private
+
+      # Each family with the members that belong to it, so a client can present
+      # sales, payments and inventory as the separate reports they are.
+      def families(metrics)
+        metrics.group_by { |metric| @registry.family_of(metric) }.map do |family, family_metrics|
+          {
+            name: family,
+            label: translate('families', family, :label),
+            metrics: family_metrics.map(&:name),
+            dimensions: @registry.dimensions.values.
+              select { |d| @allowed.call(d) && @registry.base!(d.base).family == family }.map(&:name)
+          }
+        end
+      end
+
+      def metric_entry(metric)
+        {
+          name: metric.name,
+          family: @registry.family_of(metric),
+          label: translate('metrics', metric.name, :label),
+          description: translate('metrics', metric.name, :description),
+          format: metric.format,
+          currency: (metric.money? ? @store.default_currency : nil),
+          derived: metric.derived?,
+          # A ratio is divided after aggregation, so it can be neither sorted
+          # nor filtered in SQL. Published so a builder disables those controls
+          # rather than letting a merchant discover it through a 422.
+          filterable: !metric.derived?
+        }.compact
+      end
+
+      def dimension_entry(dimension, metrics)
+        {
+          name: dimension.name,
+          label: translate('dimensions', dimension.name, :label),
+          description: translate('dimensions', dimension.name, :description),
+          type: dimension.type,
+          grains: dimension.grains,
+          lookup: dimension.lookup,
+          filter_ops: Query::FILTER_OPS,
+          # Whether this dimension can lead a query with include_empty, which
+          # is what answers "which of these never had any activity".
+          supports_include_empty: dimension.population?,
+          values: dimension.enumerated_values&.map { |value| { name: value, label: self.class.value_label(dimension, value) } },
+          # Order-level metrics cannot be broken down by line-item dimensions
+          # (they would double count) — the compiler enforces the same rule.
+          compatible_metrics: metrics.select { |m| @registry.compatible?(m, dimension) }.map(&:name)
+        }.compact
+      end
+
+      def translate(group, name, facet)
+        Spree.t("reporting.#{group}.#{name}.#{facet}", default: (facet == :label ? name.to_s.humanize : nil))
+      end
+
+
+      # Enumerated values are labelled server-side so a plugin dimension
+      # declaring `values:` needs no dashboard locale edit; the schema, the
+      # result hydration and the CSV export all read the same label.
+      #
+      # @param dimension [Registry::Dimension]
+      # @param value [String]
+      # @return [String]
+      def self.value_label(dimension, value)
+        Spree.t("reporting.values.#{dimension.name}.#{value}", default: value.to_s.humanize)
+      end
+    end
+  end
+end

data/lib/spree/reporting.rb

@@ -0,0 +1,49 @@
+require 'spree/reporting/registry'
+require 'spree/reporting/default_vocabulary'
+require 'spree/reporting/query'
+require 'spree/reporting/schema'
+require 'spree/reporting/result'
+require 'spree/reporting/counter_result'
+require 'spree/reporting/counters'
+require 'spree/reporting/hydration'
+require 'spree/reporting/adapters/base'
+require 'spree/reporting/adapters/live'
+
+module Spree
+  # Semantic reporting layer (see docs/plans/6.0-analytics-semantic-layer.md).
+  #
+  # Developers extend the vocabulary through the registry:
+  #
+  #   Spree.reporting.metric :wholesale_margin, sql: '...', base: :line_items, format: :money
+  #   Spree.reporting.dimension :warehouse, base: :orders, column: :stock_location_id, lookup: 'Spree::StockLocation'
+  #   Spree.reporting.counter :orders_on_hold, count: ->(store, channel:) { store.orders.on_hold.count }
+  #
+  # Consumers (Admin API, dashboard, saved reports, AI tools) compose queries
+  # against registered names only — see Spree::Reporting::Query.
+  module Reporting
+    # Public URL for a media row a hydrated dimension carries, or nil when the
+    # record has no file. Mirrors what the API serializers render.
+    #
+    # @param media [Spree::Media, nil]
+    # @return [String, nil]
+    def self.image_url(media)
+      attachment = media.respond_to?(:attachment) ? media.attachment : media
+      return nil unless attachment.respond_to?(:attached?) && attachment.attached?
+
+      Rails.application.routes.url_helpers.cdn_image_url(attachment)
+    end
+
+    class UnknownMember < StandardError
+      attr_reader :kind, :name, :valid
+
+      def initialize(kind, name, valid)
+        @kind = kind
+        @name = name
+        @valid = valid
+        super("Unknown reporting #{kind}: #{name}. Valid #{kind.to_s.pluralize}: #{valid.join(', ')}")
+      end
+    end
+
+    class InvalidQuery < StandardError; end
+  end
+end

data/lib/spree/service_module.rb

@@ -85,6 +85,12 @@ module Spree
         end
       end
 
+      # Rewrites the pipeline seed in place — used by kwarg-rename bridges so
+      # every subsequent step sees the canonical keys.
+      def rewrite_input!(remove: [], **merge)
+        @_passed_input = Result.new(true, @_passed_input.value.except(*remove).merge(merge))
+      end
+
       def success(value)
         Result.new(true, value, nil)
       end

data/lib/spree/store_scope_guard.rb

@@ -0,0 +1,180 @@
+require 'request_store'
+
+module Spree
+  # Development/test tripwire for cross-store data leaks
+  # (docs/plans/6.0-store-context-and-first-run-setup.md): while a guarded
+  # request runs, a SELECT against a store-owned table (any spree_* table
+  # carrying a store_id column) that is neither store-scoped nor id-filtered
+  # is reported — that is the shape of an IDOR/cross-store leak, since every
+  # controller lookup must go through a current_store association. Open-core
+  # isolation rests on that discipline (row-level enforcement is not a core
+  # feature), so this is the net under it.
+  #
+  # Never active in production — it is a correctness net for development and
+  # CI, not an enforcement layer. Mode comes from
+  # `Spree::Config[:store_scope_guard]` / SPREE_STORE_SCOPE_GUARD:
+  # 'log' (default), 'raise', or 'off'.
+  #
+  # A deliberately store-less lookup (a global credential search, a
+  # cross-store listing for the store switcher) opts out explicitly:
+  #
+  #   Spree::StoreScopeGuard.skip { Spree::ApiKey.find_by(token: token) }
+  #
+  # Flags live in RequestStore — like Spree::Events' disable flags — so a
+  # request that leaks mid-flight cannot leave a reused server thread
+  # permanently skipped or watched.
+  class StoreScopeGuard
+    class UnscopedQueryError < StandardError; end
+
+    ACTIVE_KEY = :spree_store_scope_guard_active
+    SKIP_KEY = :spree_store_scope_guard_skip
+
+    # Tables that answer store-less queries by design. spree_stores is the
+    # tenant root itself; the *_stores join tables are the legacy multi-store
+    # bridges, filtered by their other foreign key.
+    IGNORED_TABLES = %w[
+      spree_stores
+      spree_products_stores
+      spree_promotions_stores
+      spree_payment_methods_stores
+    ].freeze
+
+    class << self
+      def enabled?
+        watchable_environment? && mode != 'off'
+      end
+
+      # Overridable: OSS keeps the guard out of production, but a
+      # multi-tenant enforcement layer may run it there as a log-mode canary.
+      # Memoized — this sits on the production request path, where it must
+      # answer "no" for free.
+      def watchable_environment?
+        return @watchable_environment if defined?(@watchable_environment)
+
+        @watchable_environment = Rails.env.development? || Rails.env.test?
+      end
+
+      # @return [String] 'log', 'raise' or 'off'
+      def mode
+        Spree::Config[:store_scope_guard]
+      end
+
+      # Wraps a unit of work (an API request) in the guarded window. No-op
+      # when the guard is disabled.
+      def watch
+        return yield unless enabled?
+
+        install!
+        previous = RequestStore.store[ACTIVE_KEY]
+        RequestStore.store[ACTIVE_KEY] = true
+        yield
+      ensure
+        RequestStore.store[ACTIVE_KEY] = previous
+      end
+
+      # Suppresses the guard for a deliberately store-less lookup.
+      def skip
+        previous = RequestStore.store[SKIP_KEY]
+        RequestStore.store[SKIP_KEY] = true
+        yield
+      ensure
+        RequestStore.store[SKIP_KEY] = previous
+      end
+
+      def active?
+        RequestStore.store[ACTIVE_KEY] && !RequestStore.store[SKIP_KEY]
+      end
+
+      # Forgets memoized environment/schema state (specs, migrations).
+      def reset!
+        remove_instance_variable(:@watchable_environment) if defined?(@watchable_environment)
+        @watched_tables = nil
+      end
+
+      private
+
+      def install!
+        @installed ||= begin
+          ActiveSupport::Notifications.subscribe('sql.active_record') do |*, payload|
+            check(payload) if active?
+          end
+          true
+        end
+      end
+
+      def check(payload)
+        return if payload[:cached]
+
+        sql = payload[:sql].to_s
+        # Active Record emits uppercase keywords; hand-written lowercase SQL
+        # is out of scope for a tripwire.
+        return unless sql.start_with?('SELECT')
+
+        table = sql[/ FROM ["'`]?([a-z0-9_]+)/, 1]
+        return if table.nil? || !watched_tables.include?(table)
+        return if scoped?(sql)
+
+        report(table, sql, payload[:name])
+      end
+
+      # Deliberately crude — parsing SQL to never false-negative is not the
+      # point; catching the common leak shapes cheaply is. A statement counts
+      # as scoped when it carries:
+      #
+      # - a store_id predicate anywhere, or
+      # - any id/_id predicate: primary-key and foreign-key filters use ids
+      #   that came from rows already loaded through a scoped association, or
+      # - the `SELECT 1 AS one` existence shape, which is dominated by
+      #   uniqueness validations on deliberately global columns (document
+      #   numbers are unique across stores by design).
+      #
+      # What that trades away, honestly: attacker-controlled raw ids in
+      # store-less finds/FK filters and `exists?` probes slip through — those
+      # shapes are covered structurally (v3 resource lookups run through
+      # `for_store(current_store)`). The net catches what has no structural
+      # cover: secondary-key lookups (slug, number, code, email, token) and
+      # unscoped scans.
+      def scoped?(sql)
+        # A store_id COMPARISON, not a mention — a projected column
+        # (`select(:store_id)`) must not count, and neither does
+        # `store_id IS [NOT] NULL`, which matches storeless or all-store rows
+        # rather than a store. The optional closing quote covers every
+        # adapter: PostgreSQL/SQLite double-quote identifiers, MySQL
+        # backticks them.
+        sql.match?(/\bstore_id["'`]?\s+(=|!=|IN)\s/) ||
+          sql.start_with?('SELECT 1 AS one') ||
+          sql.match?(/\b(id|[a-z_]+_id)["'`]?\s+(=|!=|IN)\s/)
+      end
+
+      # Store-owned tables, derived from the live schema so new store-scoped
+      # models are watched without registration. The introspection itself
+      # issues queries, so it runs inside `skip` — otherwise the subscriber
+      # re-enters this method forever.
+      def watched_tables
+        @watched_tables ||= skip do
+          connection = ActiveRecord::Base.connection
+          connection.tables.select do |table|
+            table.start_with?('spree_') &&
+              !IGNORED_TABLES.include?(table) &&
+              connection.column_exists?(table, :store_id)
+          end.to_set
+        end
+      end
+
+      def report(table, sql, name)
+        # Bounded window: the interesting frame sits a few levels above the
+        # notification subscriber, and materializing a full request backtrace
+        # per violation is what makes log mode expensive.
+        frames = caller(3, 30) || []
+        location = frames.find { |line| !line.include?('/gems/') } || frames.first
+        message = "[Spree::StoreScopeGuard] store-less query on #{table} inside a guarded request " \
+                  "(#{name}): #{sql.truncate(300)}\n  at #{location}\n" \
+                  '  Scope the lookup through current_store, or wrap a deliberately global lookup in Spree::StoreScopeGuard.skip { }.'
+
+        raise UnscopedQueryError, message if mode == 'raise'
+
+        Rails.logger.warn(message)
+      end
+    end
+  end
+end