labimotion 2.3.0 → 2.4.0.rc11

data/lib/labimotion/libs/share_resolver.rb

@@ -0,0 +1,373 @@
+# frozen_string_literal: true
+
+require 'labimotion/constants'
+
+module Labimotion
+  ## ShareResolver
+  # The one place share rows are turned into an answer, for both shapes of question:
+  # `authorize` for a single record on a mutating endpoint, `context_for` for a whole grid —
+  # a hundred-template list must cost a fixed number of queries, not a lookup per row
+  # (template-sharing.md §7).
+  class ShareResolver
+    # The authorization ladder (§6). Seven names even where thresholds coincide: the call site
+    # documents intent, and the collapse stays visible in one constant instead of drifting
+    # apart across the codebase. `release_minor` (25, the maintainer's one extra right) is
+    # distinct from `release` (30, major — still owner-only) for the same reason: the two
+    # release buttons ask two different questions, and collapsing them here is how an editor
+    # once ended up refused on a button the grid had offered. Values are KlassShare::LEVELS
+    # (10 viewer / 20 editor / 25 maintainer / 30 owner) as literals — dereferencing the
+    # ActiveRecord model in this class body would force it to load in any process that touches
+    # the resolver, and the numbers are already frozen into the one-owner partial index anyway.
+    REQUIRED_LEVEL = {
+      read: 10, write: 20, release_minor: 25, release: 30, deactivate: 30, destroy: 30,
+      manage: 30
+    }.freeze
+
+    # The requester's inbox predicate (§7), verbatim from the design, as one SQL fragment
+    # because its three conjuncts are one idea: "a grant somebody else made me, which I have
+    # not seen in its current state".
+    #
+    #   permission_level >= 10
+    #     A level that actually confers access. A level-0 row is the caller's own standing ask,
+    #     and it belongs to the *owner's* queue, not to theirs.
+    #
+    #   created_by <> shared_with_id
+    #     Load-bearing, and it looks removable — it is not. Every owner row is a self-grant
+    #     written by KlassShare.seed_owner! on the create path (and by the seed migration for
+    #     everything older), so without this conjunct every designer would be told "you were
+    #     granted owner on…" for every template they ever made. A real grant re-stamps
+    #     created_by to the granter (KlassShareAPI's POST /shares), and transfer_ownership does
+    #     the same, so both still announce themselves.
+    #
+    #   acked_at IS NULL OR acked_at < updated_at
+    #     The whole ack mechanism — see KlassShare's comment on the column. There is no reset
+    #     logic: a later upgrade or transfer moves updated_at past acked_at and re-announces by
+    #     itself, and a revocation is a hard delete, so the entry disappears instead.
+    #
+    # Levels as literals for the reason REQUIRED_LEVEL gives above.
+    UNACKNOWLEDGED_GRANTS = 'permission_level >= 10 AND created_by <> shared_with_id ' \
+                            'AND (acked_at IS NULL OR acked_at < updated_at)'
+
+    # A refusal carries who to ask — naming the owner is what keeps a 403 from reading as an
+    # authorisation failure between equally authorised peers (§3).
+    Refusal = Struct.new(:owner_id)
+
+    # An owner entry in the context: the share row's user id survives even when the user
+    # record cannot be resolved, so a departed-and-purged owner still shows as "user #id
+    # (unknown)" instead of losing the id the transfer flow needs.
+    OwnerRef = Struct.new(:id, :user)
+
+    class << self
+      def key_for(klass)
+        Labimotion::KlassShare.key_of(klass)
+      end
+
+      # :ok      — the action may proceed.
+      # :legacy  — no owner row exists (or the host has not migrated): fall back to the
+      #            designer-wide authenticate_admin! gate. Permanent, not transitional — an
+      #            un-backfilled template degrades to "as before", never to "locked out".
+      # Refusal  — the template is owned and the user's level is insufficient.
+      #
+      # Resolution order: administrator (STI type 'Admin' — owner level on everything,
+      # implicit, no rows of its own) → the user's own share, a SegmentKlass taking the
+      # higher of its own level and its parent ElementKlass's → legacy fallback when no
+      # owner row exists. Errors propagate: an owned template must never fail open just
+      # because a query failed.
+      #
+      # A departed owner's row still counts as "has an owner" — ignoring it would drop the
+      # klass into the legacy gate, which is exactly the fail-open the design forbids; the
+      # row waits for the super owner's transfer instead. The requesting user's own rows
+      # need no departed filter: a deleted or deactivated user cannot be logged in.
+      def authorize(klass, user, action)
+        required = REQUIRED_LEVEL.fetch(action)
+        return :legacy unless shares_enabled?
+        return :ok if admin?(user)
+
+        level = level_for(klass, user)
+        return :ok if level && level >= required
+
+        owner_row = Labimotion::KlassShare.owner_row_for(klass)
+        return :legacy if owner_row.nil?
+
+        Refusal.new(owner_row.shared_with_id)
+      end
+
+      # Per-request preload for the grids: nil when the host has not migrated (entities then
+      # keep their pre-share behaviour), else the owner and the requesting user's level per
+      # klass key, in two share queries plus one user query however long the list is.
+      # Departed users stay in the owners map on purpose — the grid badge and the
+      # awaiting-transfer list are how anyone finds out.
+      def context_for(klasses, user)
+        return nil unless shares_enabled?
+
+        rows = Array(klasses).compact
+        shares = shares_for(rows)
+
+        {
+          admin: admin?(user),
+          has_owner: owned_keys(shares),
+          owners: owners_map(shares),
+          levels: levels_map(rows, shares, user),
+          # The requesting user's legacy designer rights per klass type: what an owner-less
+          # template falls back to. The ungated list endpoints serve non-designers too, so
+          # capability booleans must not assume everyone reading the grid holds them.
+          legacy: legacy_rights(user),
+          pending_requests: pending_requests_map(shares, user)
+        }
+      rescue StandardError => e
+        # The grid must render even if share resolution breaks; entities fall back to the
+        # pre-share display. Display only — `authorize` above deliberately has no such net.
+        Labimotion.log_exception(e)
+        nil
+      end
+
+      # The Designer's share poller (§7), over the share rows the requesting user is involved
+      # in: the rows anybody holds on the templates they own — every collaborator's, every
+      # requester's — plus the rows granting them access on other people's templates.
+      #
+      # Three values, two questions. `count` and `latest` answer "did anything about my sharing
+      # move at all", the cheap early-out a client can use alone. `digests` answers "which
+      # templates", one entry per involved klass key, each the same pair taken over that klass's
+      # rows alone — so the client re-reads the rows whose digest changed, appeared or vanished
+      # instead of reloading the whole grid. That whole-grid reload is what destroyed a
+      # Designer's unsaved edits, since re-seeding the list re-seeds the open Work Area.
+      #
+      # Opaque change tokens, not clocks. The client compares them for inequality in *either*
+      # direction, and none of this must ever grow "newer than" semantics: a revocation is a
+      # hard delete (KlassShare is deliberately not acts_as_paranoid), so a key's `latest` moves
+      # backwards while its `count` drops, or the key disappears from the map outright —
+      # precisely the events a timestamp cursor would silently stop detecting.
+      #
+      # Aggregates, never the rows: this is polled about once a minute per open Designer page,
+      # and the owner of a busy template is involved in every row on it. The per-key map is a
+      # GROUP BY over the same scope, so it costs the same two round trips the bare pair did —
+      # and the pair is then derived from the groups rather than queried again, which also makes
+      # `count` the sum of the digests' counts by construction.
+      #
+      # The administrator is an implicit owner everywhere but holds rows only where they really
+      # own something, so their token moves for their own templates alone. Same stance as
+      # pending_requests_map: it is the owner's signal, not a global one.
+      def activity_for(user)
+        return { count: 0, latest: nil, digests: {} } unless shares_enabled?
+
+        scope = involving(user).group(:klass_type, :klass_id)
+        # Two round trips over one scope rather than a hand-written SELECT COUNT(*), MAX(...):
+        # a write landing between them yields either a token that differs from the client's (a
+        # spurious refresh) or one that matches it and is superseded by the next poll a minute
+        # later. Neither loses an event, and the query stays ActiveRecord's.
+        counts = scope.count
+        latests = scope.maximum(:updated_at)
+        { count: counts.values.sum,
+          latest: latests.values.compact.max,
+          digests: digests_map(counts, latests) }
+      end
+
+      # The Designer's share inbox (§7), and the last hop of the request loop finally landing
+      # where somebody is looking: the owner's queue of standing requests, and the requester's
+      # queue of grants they have not marked seen.
+      #
+      # Both are queries over klass_shares. There is no event table and no message log by
+      # decision, so nothing can hold ack state that disagrees with the rows themselves —
+      # a second store would immediately have its own retention question and its own idea of
+      # what is outstanding.
+      #
+      # `requests` — the owner's queue: the level-0 rows on the templates the caller holds the
+      # owner row on. No column gates it and none should. A grant promotes the row off level 0
+      # and a reject hard-deletes it, so the queue empties itself; that *is* the ack, and there
+      # is deliberately no dismiss-without-acting for a column to record. It is also the same
+      # predicate pending_requests_map counts for the grid's ShareBtn badge, over the same
+      # rows — so the badge and the queue cannot disagree about what is waiting.
+      #
+      # `grants` — the requester's queue: see UNACKNOWLEDGED_GRANTS.
+      #
+      # Rows rather than aggregates, unlike activity_for on the same poll tick, and bounded by
+      # what a human can act on rather than by the size of the account: a level-0 row lasts only
+      # until somebody answers it, and a grant row only until its recipient marks it seen.
+      #
+      # At most three queries however large the account — the owned keys, then one per queue,
+      # with the requests query skipped outright for a caller who owns nothing. The caller
+      # resolves klass labels and user names on top of that, in bulk.
+      def inbox_for(user)
+        return { requests: [], grants: [] } unless shares_enabled?
+
+        { requests: pending_requests_for(user), grants: unacknowledged_grants_for(user) }
+      end
+
+      def admin?(user)
+        user.respond_to?(:type) && user.type == 'Admin'
+      end
+
+      private
+
+      # The owned keys grouped by klass_type into one exact `klass_type = ? AND klass_id IN (…)`
+      # branch each, exactly as `involving` does it — a user owns at most the three types, so the
+      # OR stays short and every branch stays indexed. The level filter lands outside the OR:
+      # `(A OR B) AND permission_level = 0`.
+      def pending_requests_for(user)
+        scope = owned_scope(owned_keys_for(user))
+        return [] if scope.nil?
+
+        scope.where(permission_level: Labimotion::KlassShare::LEVELS[:requested]).to_a
+      end
+
+      def owned_scope(keys)
+        keys.group_by(&:first).reduce(nil) do |scope, (type, group)|
+          branch = Labimotion::KlassShare.where(klass_type: type,
+                                                klass_id: group.map(&:last).uniq)
+          scope.nil? ? branch : scope.or(branch)
+        end
+      end
+
+      # One query, on the shared_with_id index.
+      def unacknowledged_grants_for(user)
+        Labimotion::KlassShare.where(shared_with_id: user.id)
+                              .where(UNACKNOWLEDGED_GRANTS)
+                              .to_a
+      end
+
+      # The grouped aggregates, re-keyed into the `"KlassType:id"` strings KlassShare.key_of
+      # produces — the same format the batch row read takes as its `keys[]`, so an entry the
+      # client saw move is directly the argument that re-reads it.
+      #
+      # The values stay a Ruby Integer and Time: turning the pair into its wire string belongs
+      # next to where `latest` is formatted, in the API, so the millisecond precision the whole
+      # token depends on is decided in exactly one place.
+      def digests_map(counts, latests)
+        counts.each_with_object({}) do |(pair, count), map|
+          map["#{pair.first}:#{pair.last}"] = { count: count, latest: latests[pair] }
+        end
+      end
+
+      # Every share row the user is involved in, as one scope: the rows naming them ORed with
+      # the rows on the templates they own. The OR is also what de-duplicates the overlap —
+      # their own owner row belongs to both halves — so nothing has to be counted twice and
+      # subtracted back.
+      #
+      # Same tuple-IN problem as rows_matching, solved the other way round. That one queries the
+      # cross-product of types and ids and narrows back to the exact keys *in Ruby*, which needs
+      # the rows in hand; an aggregate has none. Grouping the owned keys by klass_type instead
+      # makes every branch exact in SQL — `klass_type = ? AND klass_id IN (…)` — and a user owns
+      # at most the three types, so the OR stays short. Both halves are indexed: shared_with_id
+      # has an index of its own, and (klass_type, klass_id) is the leading pair of the unique
+      # klass-and-user index.
+      def involving(user)
+        mine = Labimotion::KlassShare.where(shared_with_id: user.id)
+        owned_keys_for(user).group_by(&:first).reduce(mine) do |scope, (type, keys)|
+          scope.or(Labimotion::KlassShare.where(klass_type: type,
+                                                klass_id: keys.map(&:last).uniq))
+        end
+      end
+
+      # The (klass_type, klass_id) of every template the user holds the owner row on — the one
+      # thing here that is read rather than counted, and unavoidably so: these keys *are* the
+      # predicate the aggregate is taken over. Two columns, no model instances, one lookup on
+      # the shared_with_id index.
+      def owned_keys_for(user)
+        Labimotion::KlassShare
+          .where(shared_with_id: user.id,
+                 permission_level: Labimotion::KlassShare::LEVELS[:owner])
+          .pluck(:klass_type, :klass_id)
+      end
+
+      def shares_enabled?
+        Labimotion::KlassShare.table_exists?
+      rescue StandardError
+        false
+      end
+
+      # A SegmentKlass inherits from its parent ElementKlass (§4): you cannot own an element
+      # template yet be locked out of its own segments. Datasets have no parent.
+      def parent_key(klass)
+        return nil unless klass.respond_to?(:element_klass_id) && klass.element_klass_id.present?
+
+        "ElementKlass:#{klass.element_klass_id}"
+      end
+
+      def key_of_row(row)
+        "#{row.klass_type}:#{row.klass_id}"
+      end
+
+      def level_for(klass, user)
+        keys = [key_for(klass), parent_key(klass)].compact
+        rows_matching(keys, Labimotion::KlassShare.where(shared_with_id: user.id))
+          .map(&:level).max
+      end
+
+      # One query over the cross-product of types and ids, narrowed back to the exact keys in
+      # Ruby — an IN-list per column instead of a tuple IN, which ActiveRecord 6.1 cannot
+      # express portably.
+      def shares_for(klasses)
+        keys = (klasses.map { |klz| key_for(klz) } +
+                klasses.filter_map { |klz| parent_key(klz) }).uniq
+        rows_matching(keys, Labimotion::KlassShare.all)
+      end
+
+      def rows_matching(keys, scope)
+        pairs = keys.uniq.map { |key| key.split(':') }
+        return [] if pairs.empty?
+
+        scope.where(klass_type: pairs.map(&:first).uniq,
+                    klass_id: pairs.map { |pair| pair.last.to_i }.uniq)
+             .to_a
+             .select { |row| keys.include?(key_of_row(row)) }
+      end
+
+      def owner_rows(shares)
+        shares.select { |row| row.level == Labimotion::KlassShare::LEVELS[:owner] }
+      end
+
+      def owned_keys(shares)
+        owner_rows(shares).map { |row| key_of_row(row) }.uniq
+      end
+
+      def owners_map(shares)
+        rows = owner_rows(shares)
+        users = Labimotion::OwnerResolver.map_for_ids(rows.map(&:shared_with_id))
+        rows.to_h do |row|
+          [key_of_row(row), OwnerRef.new(row.shared_with_id, users[row.shared_with_id])]
+        end
+      end
+
+      # Which legacy designer right in `users.generic_admin` answers for an owner-less klass
+      # of each type.
+      def legacy_rights(user)
+        grants = user.respond_to?(:generic_admin) && user.generic_admin.is_a?(Hash) ? user.generic_admin : {}
+        Labimotion::Constants::Family::FAMILY_OF.transform_values { |right| grants[right] == true }
+      end
+
+      # How many people are waiting on the requesting user, per template they own — what
+      # colours the Share button in the grid. A derivation over rows already in hand, not a
+      # query of its own: `shares` is every share row for the listed klasses, level-0 rows
+      # included, so the count is a select and a tally.
+      #
+      # Scoped to the user's own owner rows, which is the whole design of it. A count over
+      # every listed template would ship "somebody asked" to every viewer and editor in the
+      # payload — a signal only the person who can grant it can act on. Sparse on purpose:
+      # keys with nothing pending are absent and the entity reads a missing key as 0, so a
+      # grid of a hundred templates carries entries only for the ones actually waiting.
+      #
+      # The administrator is an implicit owner everywhere but holds no rows, so they see
+      # counts on the templates they really own and none on other people's. Correct: it is
+      # the owner's queue, not a global inbox.
+      def pending_requests_map(shares, user)
+        owned = owner_rows(shares).select { |row| row.shared_with_id == user.id }
+                                  .map { |row| key_of_row(row) }
+        return {} if owned.empty?
+
+        shares.select { |row| row.level == Labimotion::KlassShare::LEVELS[:requested] }
+              .map { |row| key_of_row(row) }
+              .select { |key| owned.include?(key) }
+              .tally
+      end
+
+      def levels_map(klasses, shares, user)
+        by_key = shares.select { |row| row.shared_with_id == user.id }
+                       .group_by { |row| key_of_row(row) }
+        klasses.to_h do |klz|
+          levels = (by_key[key_for(klz)] || []) + (by_key[parent_key(klz)] || [])
+          [key_for(klz), levels.map(&:level).max]
+        end
+      end
+    end
+  end
+end

data/lib/labimotion/libs/user_ai_settings.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Labimotion
+  ## Per-user LabIMotion AI settings: the model, an optional personal API key and
+  # an optional provider endpoint of one's own.
+  #
+  # These used to sit in the host's profile jsonb. They now live in our own
+  # user_settings table under the 'ai' key, because the settings are LabIMotion's
+  # and the host's profile is not a good place to keep growing them — see
+  # Labimotion::UserSetting.
+  #
+  # The API key is stored ENCRYPTED and never returned to a client: only whether
+  # one is set. Encryption stays the HOST's — key management is a deployment
+  # concern and a gem has no business inventing one. Chemotion supplies it as an
+  # `Encryptor` concern, pulled in below when present. A host that names its
+  # encryption differently defines `encrypt_value` / `decrypt_value` instead.
+  #
+  #   settings = Labimotion::UserAiSettings.for(current_user)
+  #   settings.model            # => 'azure.gpt-4.1'
+  #   settings.api_key?         # => true   (never the key itself, to a client)
+  #   settings.update(model: 'azure.gpt-5')
+  #
+  # `store` is injectable so the shape can be exercised without a database.
+  class UserAiSettings
+    KEY = Labimotion::Constants::UserSettingKey::AI
+
+    # Reference, not `defined?`: under Zeitwerk the latter reads nil until a
+    # constant has been touched, while referencing it triggers the autoload.
+    # rubocop:disable Layout/EmptyLinesAfterModuleInclusion -- the blank line
+    # this wants collides with EmptyLinesAroundExceptionHandlingKeywords.
+    begin
+      include Encryptor
+    rescue NameError
+      nil
+    end
+    # rubocop:enable Layout/EmptyLinesAfterModuleInclusion
+
+    attr_reader :user_id
+
+    def initialize(user_id, store: Labimotion::UserSetting)
+      @user_id = user_id
+      @store = store
+    end
+
+    # From whatever the host calls a user. Accepts the record or a bare id.
+    def self.for(user, store: Labimotion::UserSetting)
+      new(user.respond_to?(:id) ? user.id : user, store: store)
+    end
+
+    def settings
+      @store.settings_for(@user_id, KEY)
+    end
+
+    def model
+      settings['model'].presence
+    end
+
+    # Personal provider endpoint (BYO-Provider). Honored only alongside a
+    # personal key, and SSRF-validated by Labimotion::AiEgressGuard before any
+    # request is made.
+    def base_url
+      settings['base_url'].presence
+    end
+
+    def api_path
+      settings['api_path'].presence
+    end
+
+    def api_key?
+      settings['api_key'].present?
+    end
+
+    # Decrypted personal API key, or nil when none is stored.
+    def api_key
+      enc = settings['api_key']
+      return nil if enc.blank?
+
+      decrypt_value(enc).presence
+    end
+
+    # What is safe to hand a client: everything but the key, which is reported
+    # only as set-or-not.
+    def summary
+      stored = settings
+      { model: stored['model'], api_key_set: stored['api_key'].present?,
+        base_url: stored['base_url'], api_path: stored['api_path'] }
+    end
+
+    # Persist the settings. For every field: nil leaves it unchanged, a blank
+    # string clears it, anything else is stored (the api_key encrypted).
+    # Returns the safe summary — never the key itself.
+    def update(model: nil, api_key: nil, base_url: nil, api_path: nil)
+      @store.update_settings(@user_id, KEY) do |ai|
+        set_or_clear(ai, 'model', model)
+        set_or_clear_api_key(ai, api_key)
+        set_or_clear(ai, 'base_url', base_url)
+        set_or_clear(ai, 'api_path', api_path)
+        ai
+      end
+      summary
+    end
+
+    private
+
+    # nil -> leave unchanged; blank string -> clear; else store the trimmed value.
+    def set_or_clear(stored, key, value)
+      return if value.nil?
+
+      trimmed = value.to_s.strip
+      if trimmed.blank?
+        stored.delete(key)
+      else
+        stored[key] = trimmed
+      end
+    end
+
+    # As set_or_clear, but the value is encrypted on the way in.
+    def set_or_clear_api_key(stored, value)
+      return if value.nil?
+
+      trimmed = value.to_s.strip
+      if trimmed.blank?
+        stored.delete('api_key')
+      else
+        stored['api_key'] = encrypt_value(trimmed)
+      end
+    end
+  end
+end

data/lib/labimotion/models/cellline.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# This file extends the existing CelllineSample model in the consuming app
+# and defines a Labimotion::CellLine wrapper for convenient access.
+# NB: the ELN host model is ::CelllineSample, but the wrapper is named
+# Labimotion::CellLine so that "cell_line".camelize == "CellLine" resolves
+# to it in the search_basic_by_like endpoint.
+
+# rubocop:disable Style/RedundantConstantBase
+
+ActiveSupport.on_load(:active_record) do
+  if defined?(::CelllineSample)
+    ::CelllineSample.class_eval do
+      include Labimotion::ElementFetchable
+
+      def self.element_klass_name
+        'cell_line'
+      end
+    end
+  else
+    warn '[Labimotion] CelllineSample is not defined when Labimotion extension was loaded.'
+  end
+end
+
+# Namespace wrapper to keep your preferred call style
+module Labimotion
+  module CellLine
+    class << self
+      # Delegate class methods to ::CelllineSample.
+      # ruby2_keywords is required so keyword arguments survive the *args
+      # round-trip on Ruby >= 3.0 (e.g. fetch_for_user(id, name:, limit:)).
+      ruby2_keywords def method_missing(method, *args, &block)
+        if ::CelllineSample.respond_to?(method)
+          ::CelllineSample.public_send(method, *args, &block)
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(method, include_private = false)
+        ::CelllineSample.respond_to?(method, include_private) || super
+      end
+    end
+  end
+end
+
+# rubocop:enable Style/RedundantConstantBase

data/lib/labimotion/models/concerns/datasetable.rb

@@ -42,6 +42,9 @@ module Labimotion
       uuid = SecureRandom.uuid
       metadata = args[:metadata] || {}
       props = args[:properties]
+      # Datasets do not go through SampleAssociation, so they strip their own
+      # default-injected linked attributes before being stored.
+      Labimotion::LinkedElement.strip_defaults(props)
       props['pkg'] = Labimotion::Utils.pkg(props['pkg'])
       props['identifier'] = klass.identifier if klass.identifier.present?
       props['uuid'] = uuid

data/lib/labimotion/models/concerns/matrice_labimotion.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Labimotion
+  ## The LabIMotion side of a host's UI-feature model — whatever this gem needs
+  # to read out of the per-feature JSON configs an admin edits.
+  #
+  # Today that is one thing: which users may reach the AI integration. Named for
+  # the seam rather than for that one job, so the next setting we need from a
+  # feature's configs lands beside it instead of in a second concern mixed into
+  # the same model.
+  #
+  # The division throughout: which users are allowed is the HOST's decision and
+  # the host's data — an admin edits the lists on the UI Features page and they
+  # live in the host's own table. What the answer MEANS is LabIMotion's: which
+  # generic types have an AI integration, that auto-fill is a sub-gate rather
+  # than a separate one, and that every step is closed by default. So the shape
+  # lives here and the storage stays there, the same division the rest of this
+  # gem keeps with its host.
+  #
+  # Chemotion holds the configs on its `Matrice` model, which includes this:
+  #
+  #   class Matrice < ApplicationRecord
+  #     include Labimotion::MatriceLabimotion
+  #   end
+  #
+  # A host supplying it needs two things: the including model must answer
+  # `find_by(name:)` with a record exposing a `configs` hash, and its user must
+  # answer `matrix_check_by_name(name)` with whether that feature is on for them
+  # at all. Both already hold for the model this was extracted from.
+  #
+  # The configs a feature may carry:
+  #
+  #   { "ai_uids": [109, 147], "fill_uids": [109] }
+  #
+  module MatriceLabimotion
+    extend ActiveSupport::Concern
+
+    # UI features whose JSON configs may carry an AI whitelist. Each one gates the
+    # LabIMotion AI integration of its own generic type (the designer's "New (AI)"
+    # / "Fine-tune with AI" buttons, and — for genericElement — the AI auto-fill in
+    # the element detail view).
+    AI_FEATURES = %w[genericElement segment genericDataset].freeze
+
+    # The feature carrying the auto-fill whitelist. Only this one has a
+    # `fill_uids` list: auto-fill is the AI action ordinary users reach, in the
+    # element detail view, while the designer's "New (AI)" buttons on the other
+    # two types are admin-only and need no second gate.
+    FILL_FEATURE = 'genericElement'
+
+    # rubocop:disable Metrics/BlockLength -- a concern's class_methods block is a
+    # namespace for the methods it contributes, not a unit of logic to keep short.
+    class_methods do
+      # User ids allowed to use the AI integration of a UI feature, read from that
+      # feature's JSON configs:
+      #
+      #   { "ai_uids": [109] }
+      def ai_uids(name)
+        whitelist_uids(name, 'ai_uids')
+      end
+
+      # User ids allowed to run AI auto-fill, read from the same JSON configs:
+      #
+      #   { "ai_uids": [109, 147], "fill_uids": [109] }
+      #
+      # A sub-gate on ai_uids, not a separate one — auto-fill is the AI action
+      # ordinary users reach, so it is narrowed to a subset of the group that sees
+      # the integration at all. Only genericElement consults it; the designer's
+      # "New (AI)" buttons are admin-only and have no equivalent.
+      def fill_uids(name)
+        whitelist_uids(name, 'fill_uids')
+      end
+
+      # True when `user` may use the AI integration of `name`. The whitelist is a
+      # sub-gate on top of normal feature visibility, so a whitelisted user still
+      # sees nothing when the feature itself is off for them.
+      def ai_enabled_for?(user, name)
+        return false if user.nil?
+
+        ai_uids(name).include?(user.id) && user.matrix_check_by_name(name)
+      end
+
+      # { 'genericElement' => true, 'segment' => false, ... } for the UI to gate on.
+      def ai_features_for(user)
+        AI_FEATURES.index_with { |name| ai_enabled_for?(user, name) }
+      end
+
+      # True when `user` is whitelisted for at least one generic type — the gate for
+      # shared surfaces such as the "AI" tab in My LabIMotion.
+      def ai_enabled_for_any?(user)
+        AI_FEATURES.any? { |name| ai_enabled_for?(user, name) }
+      end
+
+      # True when `user` may run AI auto-fill (the wand in the generic element
+      # toolbar, POST /generic_elements/ai_fill_data). Takes no feature name
+      # because only FILL_FEATURE has such a list.
+      #
+      # Both gates must pass: `ai_uids` decides who sees the AI integration at
+      # all, `fill_uids` narrows that group. It narrows rather than widens, so a
+      # user on fill_uids alone gets nothing.
+      #
+      # The endpoint is defined in this gem and the host reports the same answer
+      # to its client, both through this one method, so the button and the
+      # endpoint can never disagree about who may use it.
+      def fill_enabled_for?(user)
+        return false if user.nil?
+
+        ai_enabled_for?(user, FILL_FEATURE) && fill_uids(FILL_FEATURE).include?(user.id)
+      end
+
+      private
+
+      # Closed by default: a missing key, a non-array value or an empty list all mean
+      # nobody. Non-numeric entries are dropped rather than raising, so a typo in the
+      # admin JSON editor narrows the whitelist instead of breaking the page.
+      def whitelist_uids(name, key)
+        uids = (find_by(name: name)&.configs || {})[key]
+        return [] unless uids.is_a?(Array)
+
+        uids.filter_map { |uid| Integer(uid, exception: false) }
+      end
+    end
+    # rubocop:enable Metrics/BlockLength
+  end
+end