labimotion 2.4.0.rc2 → 2.4.0.rc4

data/lib/labimotion/helpers/element_helpers.rb

@@ -31,7 +31,13 @@ module Labimotion
       attributes[:properties_release] = attributes[:properties_template]
       attributes[:created_by] = current_user.id
 
-      new_klass = Labimotion::ElementKlass.create!(attributes)
+      # The owner row shares the create's transaction: a klass committed without it is
+      # owner-less, which falls open to the legacy designer-wide gate.
+      new_klass = Labimotion::ElementKlass.transaction do
+        Labimotion::ElementKlass.create!(attributes).tap do |klz|
+          Labimotion::KlassShare.seed_owner!(klz, current_user.id)
+        end
+      end
       new_klass.reload
       new_klass.create_klasses_revision(current_user)
       klass_names_file = Labimotion::KLASSES_JSON # Rails.root.join('app/packs/klasses.json')
@@ -43,6 +49,184 @@ module Labimotion
       raise e
     end
 
+    # Create a new (inactive) element klass whose properties template is
+    # generated by an LLM from a user-provided name/label plus optional
+    # description, reference links and uploaded files. The admin reviews/edits
+    # the generated template in the designer and activates it (human-in-the-loop).
+    def create_ai_element_klass(params, current_user)
+      name = params[:name]
+      label = params[:label]
+      if Labimotion::ElementKlass.find_by(name: name).present?
+        return { status: 'error', message: "An element named [#{name}] already exists." }
+      end
+
+      if Array(params[:files]).size > Labimotion::AiTemplate::MAX_FILES
+        return { status: 'error', message: "Too many files (max #{Labimotion::AiTemplate::MAX_FILES})." }
+      end
+
+      overrides = ai_user_overrides(current_user)
+      ai = Labimotion::AiTemplate.generate(
+        kind: 'element',
+        subject: "#{params[:label]} (#{params[:name]})",
+        desc: params[:desc],
+        cols: params[:cols],
+        references: params[:references],
+        files: params[:files],
+        **overrides
+      )
+
+      uuid = SecureRandom.uuid
+      # property-base schema requires pkg, uuid, klass, layers, version, identifier.
+      properties_template = {
+        'uuid' => uuid,
+        'klass' => 'ElementKlass',
+        'pkg' => Labimotion::Utils.pkg(nil),
+        'version' => '1.0.0',
+        'identifier' => uuid,
+        'layers' => ai['layers'],
+        'select_options' => ai['select_options'],
+        'metadata' => ai['metadata']
+      }
+      attributes = {
+        'name' => name,
+        'label' => label,
+        'klass_prefix' => params[:klass_prefix],
+        'icon_name' => params[:icon_name],
+        'desc' => params[:desc].presence || ai['label'].presence,
+        'is_active' => false,
+        'uuid' => uuid,
+        'released_at' => DateTime.now,
+        'properties_template' => properties_template,
+        'properties_release' => properties_template,
+        'created_by' => current_user.id
+      }
+
+      new_klass = Labimotion::ElementKlass.create!(attributes)
+      new_klass.reload
+      new_klass.create_klasses_revision(current_user)
+      klass_names_file = Labimotion::KLASSES_JSON # Rails.root.join('app/packs/klasses.json')
+      klasses = Labimotion::ElementKlass.where(is_active: true)&.pluck(:name) || []
+      File.write(klass_names_file, klasses)
+      { status: 'success',
+        message: "The AI element template [#{label}] has been created as inactive. Review and activate it in the designer." }
+    rescue StandardError => e
+      Labimotion.log_exception(e, current_user)
+      { status: 'error', message: e.message }
+    end
+
+    # AI auto-fill of a generic element instance's DATA VALUES from a document
+    # (an existing attachment, an analysis, or freshly uploaded files). Reads the
+    # source text, asks the LLM to extract values for the element's OWN template
+    # fields, validates them, and returns them for the client to merge into the
+    # working copy for human review. Nothing is persisted here.
+    #
+    # Authorization: the caller must be able to READ the element, and the source
+    # must BELONG to that element (see the ownership checks below) — this endpoint
+    # reads files by id, so it must never read an Attachment/Container the user
+    # does not already have access to through this element.
+    def ai_fill_element_data(params, current_user)
+      element = Labimotion::Element.find(params[:element_id])
+      error!('401 Unauthorized', 401) unless ElementPolicy.new(current_user, element).read?
+
+      text = ai_fill_source_text(element, params)
+      overrides = ai_user_overrides(current_user)
+      ai = Labimotion::AiTemplate.fill(
+        properties: element.properties,
+        context_text: text,
+        **overrides
+      )
+      { status: 'success', values: ai['values'], summary: ai['summary'] }
+    rescue StandardError => e
+      Labimotion.log_exception(e, current_user)
+      { status: 'error', message: e.message }
+    end
+
+    # Resolve the requested source into plain text, enforcing ownership first.
+    def ai_fill_source_text(element, params)
+      case params[:source]
+      when 'attachment'
+        ai_fill_attachment_text(element, params[:attachment_id])
+      when 'analysis'
+        ai_fill_analysis_text(element, params[:container_id])
+      when 'upload'
+        ai_fill_upload_text(params[:files])
+      else
+        error!('400 Bad Request', 400)
+      end
+    end
+
+    # The attachment must be one of the element's own attachments OR an attachment
+    # of one of the element's analysis DATASET containers. Only then is it read.
+    def ai_fill_attachment_text(element, attachment_id)
+      error!('404 Not Found', 404) if attachment_id.nil?
+      error!('404 Not Found', 404) unless ai_fill_element_attachment_ids(element).include?(attachment_id.to_i)
+
+      att = Attachment.find(attachment_id)
+      Labimotion::FileExtractor.extract_bytes(att.filename, att.read_file)
+    end
+
+    # The container id must be one of the element's own analysis containers. Then
+    # concatenate the extracted text of every attachment on that analysis's dataset
+    # children, each prefixed "### <filename>", with the analysis name/description
+    # prepended as context. Cap at AiTemplate::MAX_FILES; skip unreadable files.
+    def ai_fill_analysis_text(element, container_id)
+      error!('404 Not Found', 404) if container_id.nil?
+      analysis = element.analyses.detect { |c| c.id == container_id.to_i }
+      error!('404 Not Found', 404) if analysis.nil?
+
+      parts = []
+      context = [analysis.name.presence, analysis.description.presence].compact.join(' — ')
+      parts << "Analysis: #{context}" if context.present?
+
+      ai_fill_analysis_attachments(analysis).first(Labimotion::AiTemplate::MAX_FILES).each do |att|
+        content = ai_fill_extract_attachment(att)
+        next if content.to_s.strip.empty?
+
+        parts << "### #{att.filename}\n#{content}"
+      end
+      parts.join("\n\n")
+    end
+
+    def ai_fill_upload_text(files)
+      parts = Array(files).first(Labimotion::AiTemplate::MAX_FILES).map do |file|
+        name = file[:filename] || file['filename']
+        next if name.blank?
+
+        content = Labimotion::FileExtractor.extract(name, file[:content_base64] || file['content_base64'])
+        next if content.to_s.strip.empty?
+
+        "### #{name}\n#{content}"
+      end.compact
+      parts.join("\n\n")
+    end
+
+    # Ids of attachments this element may expose to the AI fill: its own
+    # attachments plus the attachments of its analysis dataset containers.
+    def ai_fill_element_attachment_ids(element)
+      own = element.attachments.pluck(:id)
+      dataset_ids = ai_fill_dataset_containers(element).map(&:id)
+      dataset_att = dataset_ids.empty? ? [] : Attachment.where(attachable_type: 'Container', attachable_id: dataset_ids).pluck(:id)
+      (own + dataset_att).uniq
+    end
+
+    # Dataset containers under all of the element's analysis containers.
+    def ai_fill_dataset_containers(element)
+      element.analyses.flat_map { |analysis| analysis.children.where(container_type: 'dataset').to_a }
+    end
+
+    def ai_fill_analysis_attachments(analysis)
+      analysis.children.where(container_type: 'dataset').flat_map do |dataset|
+        Attachment.where(attachable_type: 'Container', attachable_id: dataset.id).to_a
+      end
+    end
+
+    def ai_fill_extract_attachment(att)
+      Labimotion::FileExtractor.extract_bytes(att.filename, att.read_file)
+    rescue StandardError => e
+      Labimotion.log_exception(e)
+      nil
+    end
+
     def update_element_klass(current_user, params)
       place = params[:place] || 100
       begin
@@ -51,6 +235,7 @@ module Labimotion
         place = 100
       end
       klass = Labimotion::ElementKlass.find(params[:id])
+      authorize_klass!(klass, :write)
       klass.label = params[:label] if params[:label].present?
       klass.klass_prefix = params[:klass_prefix] if params[:klass_prefix].present?
       klass.icon_name = params[:icon_name] if params[:icon_name].present?
@@ -305,12 +490,25 @@ module Labimotion
     end
 
     def validate_klass(attributes)
-      element_klass = Labimotion::ElementKlass.find_by(identifier: attributes['identifier'])
+      # Guarded on presence like the segment path: a blank identifier must mean "create",
+      # never `find_by(identifier: nil)` — that would match an arbitrary legacy row whose
+      # identifier is NULL and upgrade an unrelated template.
+      element_klass = Labimotion::ElementKlass.find_by(identifier: attributes['identifier']) if attributes['identifier'].present?
       if element_klass.present?
         if element_klass['uuid'] == attributes['uuid'] && element_klass['version'] == attributes['version']
           return { status: 'success', message: "This element: #{attributes['name']} has the latest version!" }
         else
-          element_klass.update!(attributes)
+          # Upgrading an existing template bumps its version and cuts a revision — publishing,
+          # which is what :release means, so it is owner-only. The gate has to live here, not
+          # in after_validation: which branch applies is unknown until this identifier lookup
+          # has run. error! throws rather than raises, so it escapes this method's rescue.
+          authorize_klass!(element_klass, :release)
+          # And it must not reassign authorship. `upload_klass` merges
+          # `created_by: current_user.id` into the attributes unconditionally
+          # (generic_element_api.rb), so without this the importer silently becomes the author
+          # of a template somebody else wrote — and that column is what the Owner column shows
+          # and what per-template ownership is seeded from.
+          element_klass.update!(attributes.except('created_by', :created_by))
           element_klass.create_klasses_revision(current_user)
           return { status: 'success', message: "This element: [#{attributes['name']}] has been upgraded to the version: #{attributes['version']}!" }
         end
@@ -320,7 +518,11 @@ module Labimotion
           return { status: 'error', message: "The name [#{attributes['name']}] is already in use." }
         else
           attributes['created_by'] = current_user.id
-          element_klass = Labimotion::ElementKlass.create!(attributes)
+          element_klass = Labimotion::ElementKlass.transaction do
+            Labimotion::ElementKlass.create!(attributes).tap do |klz|
+              Labimotion::KlassShare.seed_owner!(klz, current_user.id)
+            end
+          end
           element_klass.create_klasses_revision(current_user)
           return { status: 'success', message: "The element: #{attributes['name']} has been created using version: #{attributes['version']}!" }
         end

data/lib/labimotion/helpers/generic_helpers.rb

@@ -1,22 +1,105 @@
 # frozen_string_literal: true
 require 'grape'
 require 'labimotion/conf'
+require 'labimotion/constants'
 require 'labimotion/utils/utils'
+require 'labimotion/libs/owner_resolver'
 # Helper for associated sample
 module Labimotion
   ## Generic Helpers
   module GenericHelpers
     extend Grape::API::Helpers
 
+    # Message code for "somebody else saved this template while you were editing it".
+    STALE_TEMPLATE_MC = 'sc09'
+    # Message code for "an active template already holds the identity you are restoring".
+    RESTORE_CONFLICT_MC = 'sc10'
+    # Message code for "this template is maintained by somebody else" — the 403 a share-gated
+    # action answers with. Deliberately not the legacy 401: nobody here is unauthorised, they
+    # are asking about a colleague's template (template-sharing.md §3).
+    AUTHORIZATION_REFUSAL_MC = 'sc11'
+    # Message code for "the owner row cannot be removed or downgraded — transfer instead".
+    OWNER_ROW_MC = 'sc12'
+    # Message code for "you already hold access to this template, so there is nothing to
+    # request". The 409 request_access answers a caller whose share row is already at
+    # viewer/editor/owner — a stale grid, not a mistake worth an error banner.
+    ACCESS_ALREADY_HELD_MC = 'sc13'
+
+    # How a refusal names the action it refused, and which actions are owner-only for the
+    # wording. Kept as plain symbols here rather than reading ShareResolver::REQUIRED_LEVEL —
+    # the wording must not chain-load the ActiveRecord model in a process that only wanted
+    # the helpers. ShareResolver stays the enforcement authority.
+    ACTION_PHRASE = {
+      read: 'view', write: 'edit', release: 'release',
+      deactivate: 'activate or deactivate', destroy: 'delete', manage: 'manage sharing for'
+    }.freeze
+    OWNER_ONLY_ACTIONS = %i[release deactivate destroy manage].freeze
+
+    # What makes a klass unique among the *active* rows. These are model validations only —
+    # there is no DB unique index behind any of them — and `restore!` writes through
+    # `update_columns`, so nothing re-checks them on the way back in.
+    KLASS_IDENTITY = {
+      'ElementKlass' => %i[name],
+      'SegmentKlass' => %i[label element_klass_id],
+      'DatasetKlass' => %i[ols_term_id]
+    }.freeze
+
+    # How the refusal names the identity that is taken.
+    KLASS_IDENTITY_NOUN = {
+      'ElementKlass' => 'name',
+      'SegmentKlass' => 'label',
+      'DatasetKlass' => 'ontology term'
+    }.freeze
+
+    # Seconds, symmetric around the deleted template's own `deleted_at`, within which a
+    # soft-deleted child counts as "deleted together with it" (see Paranoia#restore!).
+    # Wide enough to cover a slow cascade over a template with many elements, narrow enough
+    # that rows binned on their own, on another day, stay binned.
+    RESTORE_RECOVERY_WINDOW = 300
+
     def authenticate_admin!(type)
       unauthorized = -> { error!('401 Unauthorized', 401) }
       if %w[standard_layers vocabularies].include?(type)
-        unauthorized.call unless current_user.generic_admin.values_at('elements', 'segments', 'datasets').any?
+        unauthorized.call unless current_user.generic_admin.values_at(*Labimotion::Constants::Family::ALL).any?
       else
         unauthorized.call unless current_user.generic_admin[type]
       end
     end
 
+    # Family string (Constants::Family) for a loaded klass record — what the legacy gate
+    # keys on.
+    def klass_family(klz)
+      Labimotion::Constants::Family::FAMILY_OF[klz.class.name.split('::').last]
+    end
+
+    # The per-template gate (template-sharing.md §6). Takes the record, not a family string:
+    # resolution needs that klass's share rows and, for a SegmentKlass, its parent element's.
+    # Owner-less templates (and hosts that have not migrated) fall back to the legacy
+    # designer-wide gate — permanent behaviour, not a transition. A refusal is a 403 naming
+    # the owner, so the person refused knows who to ask, never the legacy bare 401.
+    def authorize_klass!(klz, action)
+      result = Labimotion::ShareResolver.authorize(klz, current_user, action)
+      return if result == :ok
+      return authenticate_admin!(klass_family(klz)) if result == :legacy
+
+      owner = Labimotion::OwnerResolver.find(result.owner_id)
+      name = owner.respond_to?(:name) && owner.name.present? ? owner.name : 'another user'
+      error!({ mc: AUTHORIZATION_REFUSAL_MC,
+               msg: authorization_refusal_msg(name, action),
+               owner: { id: result.owner_id, name: name == 'another user' ? nil : name } }, 403)
+    end
+
+    def authorization_refusal_msg(name, action)
+      requirement = if OWNER_ONLY_ACTIONS.include?(action)
+                      "Only the owner can #{ACTION_PHRASE[action]} this template."
+                    elsif action == :read
+                      "You need shared access to #{ACTION_PHRASE[action]} this template."
+                    else
+                      "You need edit access to #{ACTION_PHRASE[action]} this template."
+                    end
+      "This template is maintained by #{name}. #{requirement}"
+    end
+
     def fetch_klass(name, id)
       klz = "Labimotion::#{name}".constantize.find_by(id: id)
       error!("#{name.gsub(/(Klass)/, '')} is invalid. Please re-select.", 500) if klz.nil?
@@ -26,8 +109,71 @@ module Labimotion
       raise e
     end
 
+    # Per-user AI overrides (model + API key) resolved from the host app's user
+    # profile. Returns {} when the host doesn't expose them, so AiTemplate falls
+    # back to the server-wide yml/ENV configuration. Guarded with respond_to? to
+    # keep the gem decoupled from the host's Profile implementation. Shared by the
+    # dataset / element / segment AI helpers.
+    def ai_user_overrides(current_user)
+      profile = current_user.respond_to?(:profile) ? current_user.profile : nil
+      return {} if profile.nil?
+
+      model   = (profile.labimotion_ai_model if profile.respond_to?(:labimotion_ai_model))
+      api_key = (profile.labimotion_ai_api_key if profile.respond_to?(:labimotion_ai_api_key))
+      model   = ai_shared_key_model(model) if api_key.blank?
+
+      { model: model, api_key: api_key }.merge(ai_provider_overrides(profile, api_key)).compact
+    rescue StandardError => e
+      Labimotion.log_exception(e, current_user)
+      {}
+    end
+
+    # Personal provider endpoint (base_url/api_path) — honored only ALONGSIDE a
+    # personal key, so the shared server key is never sent to a user-supplied URL.
+    # The base_url itself is SSRF-validated later, in AiTemplate.
+    def ai_provider_overrides(profile, api_key)
+      return {} if api_key.blank?
+
+      {
+        base_url: (profile.labimotion_ai_base_url if profile.respond_to?(:labimotion_ai_base_url)),
+        api_path: (profile.labimotion_ai_api_path if profile.respond_to?(:labimotion_ai_api_path))
+      }
+    end
+
+    # On the SHARED server key (user has no personal key), keep the user's model
+    # only if the admin allowed it; otherwise return nil so AiTemplate falls back
+    # to the server default. Returns the model unchanged when no allowlist is
+    # configured (fail open). Guards an off-list model being billed to the shared key.
+    def ai_shared_key_model(model)
+      return model if model.blank?
+
+      allow = ai_server_model_allowlist
+      allow.any? && !allow.include?(model.to_s) ? nil : model
+    end
+
+    # Model ids the server permits on the SHARED key: the admin pick-list
+    # (:models) plus the server default (:model / KI_TOOLBOX_MODEL), read from the
+    # host config the same way Labimotion::AiTemplate does. Empty when the admin
+    # configured neither — the caller then skips the clamp (fail open), matching
+    # the gem's decoupled, non-blocking handling of overrides.
+    def ai_server_model_allowlist
+      cfg = Rails.configuration.labimotion_ai || {}
+      list = cfg[:models].is_a?(Array) ? cfg[:models] : []
+      ids = list.map { |entry| ai_model_entry_id(entry) }
+      (ids << cfg[:model].to_s << ENV['KI_TOOLBOX_MODEL'].to_s).reject(&:blank?).uniq
+    rescue StandardError
+      []
+    end
+
+    def ai_model_entry_id(entry)
+      return entry.to_s unless entry.is_a?(Hash)
+
+      (entry[:id] || entry['id']).to_s
+    end
+
     def deactivate_klass(params)
       klz = fetch_klass(params[:klass], params[:id])
+      authorize_klass!(klz, :deactivate)
       klz&.update!(is_active: params[:is_active])
       generate_klass_file unless klz.class.name != 'Labimotion::ElementKlass'
       klz
@@ -38,6 +184,7 @@ module Labimotion
 
     def update_klass_settings(params)
       klz = fetch_klass(params[:klass], params[:id])
+      authorize_klass!(klz, :write)
       klz&.update!(settings: (klz.settings || {}).merge(params[:settings] || {}))
       klz
     rescue StandardError => e
@@ -46,8 +193,8 @@ module Labimotion
     end
 
     def delete_klass(params)
-      authenticate_admin!(params[:klass].gsub(/(Klass)/, 's').downcase)
       klz = fetch_klass(params[:klass], params[:id])
+      authorize_klass!(klz, :destroy)
       klz&.destroy!
       generate_klass_file unless klz.class.name != 'Labimotion::ElementKlass'
       status 201
@@ -58,6 +205,11 @@ module Labimotion
 
     def update_template(params, current_user)
       klz = fetch_klass(params[:klass], params[:id])
+      # The split that makes `editor` mean "drafting only": a draft save needs :write, while
+      # anything else bumps the version and cuts a revision — publishing, which is :release.
+      # Authorization before the stale check: who may act comes before whether the copy is fresh.
+      authorize_klass!(klz, params[:release] == 'draft' ? :write : :release)
+      guard_stale_template!(klz, params[:properties_template])
       uuid = SecureRandom.uuid
       properties = params[:properties_template]
       properties['uuid'] = uuid
@@ -79,12 +231,133 @@ module Labimotion
       raise e
     end
 
+    # A template save replaces `properties_template` wholesale, so two designers holding the
+    # same template open used to overwrite each other with no warning and nothing to recover
+    # from: drafts are never snapshotted (`Utils.next_version` is a no-op for 'draft' and
+    # `create_klasses_revision` is skipped), and making drafts cut revisions is not an option
+    # because cutting a revision writes `properties_release` — it publishes.
+    #
+    # `update_template` already mints a fresh uuid into the template on every save, so the
+    # stored uuid is a ready-made optimistic-locking token: the client posts back the uuid it
+    # was handed, and a difference means somebody saved in between.
+    #
+    # Blank on either side means we cannot tell — a template stored before this guard existed,
+    # or a client that dropped the field — and a template with no stored uuid must not start
+    # refusing saves.
+    def guard_stale_template!(klz, properties)
+      held = klz.properties_template.is_a?(Hash) ? klz.properties_template['uuid'] : nil
+      sent = properties.is_a?(Hash) ? properties['uuid'] : nil
+      return if held.blank? || sent.blank? || held == sent
+
+      error!(stale_template_error(klz), 409)
+    end
+
+    # Naming the other designer is what turns a refusal into something a user can act on, but
+    # it is decoration: `OwnerResolver.find` returns nil rather than raising, so a lookup that
+    # fails costs the name and leaves the refusal itself intact.
+    def stale_template_error(klz)
+      saver = Labimotion::OwnerResolver.find(klz.updated_by)
+      name = saver.respond_to?(:name) ? saver.name : nil
+      name = nil if name.blank?
+      { mc: STALE_TEMPLATE_MC,
+        msg: stale_template_msg(name, klz.updated_at),
+        saved_by: { id: klz.updated_by, name: name },
+        saved_at: klz.updated_at.blank? ? nil : klz.updated_at.iso8601 }
+    end
+
+    def stale_template_msg(name, saved_at)
+      who = name.blank? ? 'Another user' : name
+      moment = saved_at.blank? ? 'after you opened it' : "at #{saved_at.strftime('%Y-%m-%d %H:%M %Z')}"
+      "#{who} saved this template #{moment}, so your copy is out of date; " \
+        'reload the template and re-apply your changes.'
+    end
+
+    # `delete_klass` soft-deletes (the klasses are `acts_as_paranoid`), but nothing could list
+    # or restore the result, so recovery meant direct database access.
+    def deleted_klasses(params)
+      "Labimotion::#{params[:klass]}".constantize.only_deleted.order(deleted_at: :desc)
+    rescue StandardError => e
+      Labimotion.log_exception(e, current_user)
+      raise e
+    end
+
+    def restore_klass(params)
+      klz = fetch_deleted_klass(params[:klass], params[:id])
+      # Restore is delete's inverse and carries the same cascade into elements, so it takes
+      # the same :destroy level. Shares survive deletion, so the owner row is still there to
+      # answer this.
+      authorize_klass!(klz, :destroy)
+      guard_restore_conflict!(params[:klass], klz)
+      # `recursive` is what brings the template's elements/segments back with it; without it
+      # paranoia restores the klass row alone and every child stays deleted. The window keeps
+      # that cascade to the children deleted *with* the template.
+      klz.restore!(recursive: true, recovery_window: RESTORE_RECOVERY_WINDOW)
+      generate_klass_file if params[:klass] == 'ElementKlass'
+      klz.reload
+    rescue StandardError => e
+      Labimotion.log_exception(e, current_user)
+      raise e
+    end
+
+    def fetch_deleted_klass(name, id)
+      klz = "Labimotion::#{name}".constantize.only_deleted.find_by(id: id)
+      error!("#{name.gsub(/(Klass)/, '')} is not in the deleted list. Please refresh.", 404) if klz.nil?
+      klz
+    end
+
+    # `restore!` writes through `update_columns`, so the uniqueness validations do not run, and
+    # no DB unique index backs them either. Restoring onto a taken identity would leave two
+    # active rows with the same one, and the ten `find_by(name:)` call sites in the gem — two of
+    # which pick the `properties_release` that renders real elements — would then resolve it
+    # arbitrarily. Refuse instead, and let a human decide which row keeps the name.
+    def guard_restore_conflict!(name, klz)
+      keys = KLASS_IDENTITY[name]
+      other = conflicting_active_klass(name, keys, klz)
+      return if other.nil?
+
+      error!({ mc: RESTORE_CONFLICT_MC,
+               msg: restore_conflict_msg(name, other, keys),
+               blocked_by: { id: other.id, label: klass_label(other, keys) } }, 409)
+    end
+
+    def conflicting_active_klass(name, keys, klz)
+      return nil if keys.nil?
+
+      identity = keys.to_h { |key| [key, klz.public_send(key)] }
+      return nil if identity[keys.first].blank?
+
+      # The default scope of a paranoid model excludes deleted rows, so this can only match an
+      # active one — never the row being restored.
+      "Labimotion::#{name}".constantize.where(identity).first
+    end
+
+    def restore_conflict_msg(name, other, keys)
+      "Cannot restore: the active #{name.gsub(/(Klass)/, '')} \"#{klass_label(other, keys)}\" " \
+        "(id #{other.id}) already uses this #{KLASS_IDENTITY_NOUN[name]}."
+    end
+
+    def klass_label(klz, keys)
+      label = klz.respond_to?(:label) ? klz.label : nil
+      label.blank? ? klz.public_send(keys.first).to_s : label
+    end
+
+    # The revision must belong to the klass the caller named: the klass row is what
+    # authorize_klass! (and the active-revision guard) runs on, so accepting a mismatched
+    # pair would let ownership of one template authorize deleting — even the active —
+    # revisions of another.
+    def revision_of_klass?(revision, klass, klass_name)
+      foreign_key = "#{klass_name.sub('Klass', '_klass').downcase}_id"
+      !klass.nil? && revision.public_send(foreign_key) == klass.id
+    end
+
     def delete_klass_revision(params)
       revision = "Labimotion::#{params[:klass]}esRevision".constantize.find(params[:id])
       klass = "Labimotion::#{params[:klass]}".constantize.find_by(id: params[:klass_id]) unless revision.nil?
       error!('Revision is invalid.', 404) if revision.nil?
+      error!('Revision is invalid.', 404) unless revision_of_klass?(revision, klass, params[:klass])
+      authorize_klass!(klass, :destroy)
       error!('Can not delete the active revision.', 405) if revision.uuid == klass.uuid
-      revision&.destroy!
+      revision.destroy!
     rescue StandardError => e
       Labimotion.log_exception(e, current_user)
       raise e
@@ -110,7 +383,6 @@ module Labimotion
       raise e
     end
 
-
     ###############
     def generate_klass_file
       klass_names_file = Labimotion::KLASSES_JSON # Rails.root.join('app/packs/klasses.json')

data/lib/labimotion/helpers/param_helpers.rb

@@ -35,6 +35,74 @@ module Labimotion
       optional :properties_template, type: Hash, desc: 'Element Klass properties template'
     end
 
+    params :create_ai_dataset_klass_params do
+      requires :ols_term_id, type: String, desc: 'CHMO ontology term (e.g. "CHMO:0000470 | mass spectrometry (MS)")'
+      optional :desc, type: String, desc: 'Description / intent of the new dataset template'
+      optional :cols, type: Integer, values: 1..6, default: 1, desc: 'Default columns per row for generated layers'
+      optional :references, type: Array[String], desc: 'Reference links (publications / standards)'
+      optional :files, type: Array, desc: 'Reference files for context' do
+        optional :filename, type: String, desc: 'File name'
+        optional :content, type: String, desc: 'Client-read plaintext (legacy, truncated)'
+        optional :content_base64, type: String, desc: 'Base64-encoded raw file bytes (PDF/Excel/text — preferred)'
+      end
+    end
+
+    params :create_ai_element_klass_params do
+      requires :name, type: String, desc: 'Element Klass Name'
+      requires :label, type: String, desc: 'Element Klass Label'
+      requires :klass_prefix, type: String, desc: 'Element Klass Short Label Prefix'
+      optional :icon_name, type: String, desc: 'Element Klass Icon Name'
+      optional :desc, type: String, desc: 'Description / intent of the new element template'
+      optional :cols, type: Integer, values: 1..6, default: 1, desc: 'Default columns per row for generated layers'
+      optional :references, type: Array[String], desc: 'Reference links (publications / standards)'
+      optional :files, type: Array, desc: 'Reference files for context' do
+        optional :filename, type: String, desc: 'File name'
+        optional :content, type: String, desc: 'Client-read plaintext (legacy, truncated)'
+        optional :content_base64, type: String, desc: 'Base64-encoded raw file bytes (PDF/Excel/text — preferred)'
+      end
+    end
+
+    # AI auto-fill of a generic element instance's DATA VALUES from a document.
+    # `files` mirrors the create_ai_*_klass_params file block (source == 'upload').
+    params :ai_fill_element_data_params do
+      requires :element_id, type: Integer, desc: 'Generic element id whose data values to fill'
+      requires :source, type: String, values: %w[attachment analysis upload], desc: 'Value source'
+      optional :attachment_id, type: Integer, desc: 'Attachment id (required when source == attachment)'
+      optional :container_id, type: Integer, desc: 'Analysis container id (required when source == analysis)'
+      optional :files, type: Array, desc: 'Uploaded files (source == upload)' do
+        optional :filename, type: String, desc: 'File name'
+        optional :content, type: String, desc: 'Client-read plaintext (legacy, truncated)'
+        optional :content_base64, type: String, desc: 'Base64-encoded raw file bytes (PDF/Excel/text — preferred)'
+      end
+    end
+
+    params :create_ai_segment_klass_params do
+      requires :label, type: String, desc: 'Segment Klass Label'
+      requires :element_klass, type: Integer, desc: 'Parent Element Klass Id'
+      optional :metadata, type: Hash, desc: 'Klass metadata (segment render kind, e.g. { is_properties })'
+      optional :desc, type: String, desc: 'Description / intent of the new segment template'
+      optional :cols, type: Integer, values: 1..6, default: 1, desc: 'Default columns per row for generated layers'
+      optional :references, type: Array[String], desc: 'Reference links (publications / standards)'
+      optional :files, type: Array, desc: 'Reference files for context' do
+        optional :filename, type: String, desc: 'File name'
+        optional :content, type: String, desc: 'Client-read plaintext (legacy, truncated)'
+        optional :content_base64, type: String, desc: 'Base64-encoded raw file bytes (PDF/Excel/text — preferred)'
+      end
+    end
+
+    params :refine_ai_dataset_klass_params do
+      requires :instruction, type: String, desc: 'Natural-language change to apply to the template'
+      optional :label, type: String, desc: 'Current template label'
+      optional :ols_term_id, type: String, desc: 'CHMO ontology term (context only)'
+      optional :cols, type: Integer, values: 1..6, default: 1, desc: 'Fallback columns per row when a layer omits its own'
+      optional :layers, type: Hash, desc: 'Current template layers'
+      optional :select_options, type: Hash, desc: 'Current template select options'
+      optional :history, type: Array, desc: 'Prior chat turns for continuity' do
+        optional :role, type: String, desc: 'user | assistant'
+        optional :content, type: String, desc: 'Message content'
+      end
+    end
+
     params :update_element_klass_params do
       requires :id, type: Integer, desc: 'Element Klass ID'
       optional :label, type: String, desc: 'Element Klass Label'