labimotion 2.3.0 → 2.4.0.rc11

data/lib/labimotion/helpers/generic_helpers.rb

@@ -1,22 +1,110 @@
 # 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',
+      release_minor: 'release a minor version of',
+      deactivate: 'activate or deactivate', destroy: 'delete', manage: 'manage sharing for'
+    }.freeze
+    # `release_minor` is deliberately NOT here: a maintainer holds it too, so its refusal
+    # must not claim "only the owner can" — it gets its own maintainer wording below.
+    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 == :release_minor
+                      "You need maintainer access to #{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 +114,66 @@ module Labimotion
       raise e
     end
 
+    # Per-user AI overrides (model + API key) from the user's own settings row.
+    # Returns {} when nothing is stored, so AiTemplate falls back to the
+    # server-wide yml/ENV configuration. Shared by the dataset / element /
+    # segment AI helpers.
+    def ai_user_overrides(current_user)
+      return {} if current_user.nil?
+
+      settings = Labimotion::UserAiSettings.for(current_user)
+      api_key = settings.api_key
+      model   = api_key.blank? ? ai_shared_key_model(settings.model) : settings.model
+
+      { model: model, api_key: api_key }.merge(ai_provider_overrides(settings, 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(settings, api_key)
+      return {} if api_key.blank?
+
+      { base_url: settings.base_url, api_path: settings.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
@@ -36,9 +182,19 @@ module Labimotion
       raise e
     end
 
+    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
+      Labimotion.log_exception(e, current_user)
+      raise e
+    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
@@ -49,6 +205,19 @@ module Labimotion
 
     def update_template(params, current_user)
       klz = fetch_klass(params[:klass], params[:id])
+      # The split that makes `editor` mean "drafting only" and `maintainer` mean "drafting
+      # plus minor releases": a draft save needs :write; a minor release bumps the version
+      # and cuts a revision, which a maintainer may do (:release_minor); a major release —
+      # and any release value nobody recognises — stays owner-only (:release), so an unknown
+      # value fails toward the stricter gate.
+      # Authorization before the stale check: who may act comes before whether the copy is fresh.
+      release_action = case params[:release]
+                       when 'draft' then :write
+                       when 'minor' then :release_minor
+                       else :release
+                       end
+      authorize_klass!(klz, release_action)
+      guard_stale_template!(klz, params[:properties_template])
       uuid = SecureRandom.uuid
       properties = params[:properties_template]
       properties['uuid'] = uuid
@@ -70,12 +239,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
@@ -101,7 +391,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

@@ -14,6 +14,7 @@ module Labimotion
       optional :klass_prefix, type: String, desc: 'Klass klass_prefix'
       optional :icon_name, type: String, desc: 'Klass icon_name'
       optional :metadata, type: Hash, desc: 'Klass metadata'
+      optional :settings, type: Hash, desc: 'Klass settings'
       requires :properties_template, type: Hash, desc: 'Klass template'
       optional :properties_release, type: Hash, desc: 'Klass release'
       optional :released_at, type: DateTime, desc: 'Klass released_at'
@@ -34,6 +35,88 @@ 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 text], 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 :text, type: String, desc: 'Pasted plain text (source == text)'
+      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 :plan_ai_dataset_klass_params do
+      requires :instruction, type: String, desc: 'Natural-language change to apply to the template'
+      optional :ols_term_id, type: String, desc: 'CHMO ontology term (context only)'
+      # The INDEX, not the template: layer/field keys, labels and types only. Left
+      # as an opaque Hash because the gem only relays it — the client builds it and
+      # the client consumes the plan that comes back.
+      optional :index, type: Hash, desc: 'Compact index of the open template (keys, labels, types, groups)'
+      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'
@@ -72,6 +155,7 @@ module Labimotion
       requires :label, type: String, desc: 'Klass label'
       optional :desc, type: String, desc: 'Klass desc'
       optional :metadata, type: Hash, desc: 'Klass metadata'
+      optional :settings, type: Hash, desc: 'Klass settings'
       requires :properties_template, type: Hash, desc: 'Klass template'
       optional :properties_release, type: Hash, desc: 'Klass release'
       optional :released_at, type: DateTime, desc: 'Klass released_at'
@@ -91,6 +175,7 @@ module Labimotion
       optional :desc, type: String, desc: 'Segment Klass Desc'
       optional :place, type: String, desc: 'Segment Klass Place', default: '100'
       optional :identifier, type: String, desc: 'Segment Identifier'
+      optional :metadata, type: Hash, desc: 'Klass metadata'
     end
 
     params :create_segment_klass_params do
@@ -152,5 +237,25 @@ module Labimotion
       requires :id, type: Integer, desc: 'Element ID'
       requires :wellplate_ids, type: Array, desc: 'Selected Wellplates'
     end
+
+    params :user_klass_settings_save do
+      requires :klass, type: String, values: Labimotion::Constants::Klass::USER_SETTINGS, desc: 'Klass type'
+      requires :klass_identifier, type: String, desc: 'Stable klass identifier'
+      optional :klass_label, type: String, desc: 'Klass label (display only)'
+      requires :settings, type: Hash do
+        optional :toolbar, type: Hash do
+          optional :overview, type: Boolean, default: true
+          optional :arrange, type: Boolean, default: true
+        end
+        # The user's default inline attributes for elements linked from a
+        # drag field. Only the identity of each attribute is stored; the values
+        # are resolved live on every load. An empty array clears the default.
+        optional :linked_el_attrs, type: Array do
+          requires :key, type: String, desc: 'Attribute key (layer::field, or column name)'
+          optional :source, type: String, desc: 'property or column'
+          optional :label, type: String, desc: 'Attribute label (display only)'
+        end
+      end
+    end
   end
 end

data/lib/labimotion/helpers/sample_association_helpers.rb

@@ -19,6 +19,13 @@ module Labimotion
       []
     end
 
+    def build_table_element(field_tables, current_user, element)
+      Labimotion::SampleAssociation.build_table_element(field_tables, current_user, element)
+    rescue StandardError => e
+      Labimotion.log_exception(e, current_user)
+      []
+    end
+
     def update_sample_association(properties, current_user, element)
       Labimotion::SampleAssociation.update_sample_association(properties, current_user, element)
     rescue StandardError => e

data/lib/labimotion/helpers/segment_helpers.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 require 'grape'
-require 'labimotion/models/segment_klass'
+# require 'labimotion/models/segment_klass' — the constant resolves through the gem's
+# autoload table at call time, like the element path; an eager require drags ActiveRecord
+# into any process that only wants the helpers (element_helpers keeps its own model require
+# commented for the same reason).
 require 'labimotion/utils/utils'
 
 module Labimotion
@@ -36,7 +39,13 @@ module Labimotion
       attributes[:uuid] = uuid
       attributes[:released_at] = DateTime.now
       attributes[:properties_release] = attributes[:properties_template]
-      klass = Labimotion::SegmentKlass.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.
+      klass = Labimotion::SegmentKlass.transaction do
+        Labimotion::SegmentKlass.create!(attributes).tap do |klz|
+          Labimotion::KlassShare.seed_owner!(klz, current_user.id)
+        end
+      end
       klass.reload
       klass.create_klasses_revision(current_user)
       klass
@@ -45,8 +54,86 @@ module Labimotion
       raise e
     end
 
+    # Create a new (inactive) segment klass whose properties template is
+    # generated by an LLM from a user-provided label plus optional description,
+    # reference links and uploaded files. The parent ElementKlass must be set on
+    # @klass by the API (after_validation), mirroring create_segment_klass. The
+    # admin reviews/edits the generated template in the designer and activates it.
+    def create_ai_segment_klass(current_user, params)
+      return { status: 'error', message: 'A parent element class is required.' } if @klass.nil?
+
+      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: 'segment',
+        subject: params[:label],
+        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' => 'SegmentKlass',
+        'pkg' => Labimotion::Utils.pkg(nil),
+        'version' => '1.0.0',
+        'identifier' => uuid,
+        'layers' => ai['layers'],
+        'select_options' => ai['select_options'],
+        'metadata' => ai['metadata']
+      }
+      attributes = {
+        'label' => params[:label],
+        'desc' => params[:desc].presence || ai['label'].presence,
+        'element_klass' => @klass,
+        'place' => 100,
+        'is_active' => false,
+        'uuid' => uuid,
+        'released_at' => DateTime.now,
+        'properties_template' => properties_template,
+        'properties_release' => properties_template,
+        'created_by' => current_user.id
+      }
+      # Klass-level segment metadata (render kind: own tab vs the host element's
+      # Properties tab), mirroring the non-AI create_segment_klass which persists
+      # params[:metadata] via declared. Absent -> leave the column default.
+      attributes['metadata'] = params[:metadata] if params[:metadata].present?
+
+      # Same as the non-AI create beside it: the owner row shares the create's
+      # transaction, because a klass committed without one is owner-less and
+      # falls OPEN to the legacy designer-wide gate — every designer of the
+      # family could then edit, release and delete it, while its creator holds
+      # no special standing at all. seed_owner! rescues only RecordNotUnique and
+      # RecordInvalid, so any other failure has to take the klass down with it;
+      # this helper turns every StandardError into { status: 'error' }, and
+      # without the transaction the caller would be told the create failed while
+      # an unowned template silently persisted.
+      klass = Labimotion::SegmentKlass.transaction do
+        Labimotion::SegmentKlass.create!(attributes).tap do |klz|
+          Labimotion::KlassShare.seed_owner!(klz, current_user.id)
+        end
+      end
+      klass.reload
+      klass.create_klasses_revision(current_user)
+      # `record` is the row itself. The background job that calls this needs the
+      # template, not a sentence about it, to link the notification back to it.
+      { status: 'success', record: klass,
+        message: "The AI segment template [#{params[: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
+
     def update_segment_klass(current_user, params)
       segment = fetch_klass('SegmentKlass', params[:id])
+      authorize_klass!(segment, :write)
       place = params[:place]
       begin
         place = place.to_i if place.present? && place.to_i == place.to_f
@@ -77,7 +164,14 @@ module Labimotion
         if segment_klass['uuid'] == attributes['uuid'] && segment_klass['version'] == attributes['version']
           return { status: 'success', message: "This segment: #{attributes['label']} has the latest version!" }
         else
-          segment_klass.update!(attributes)
+          # Upgrading bumps the version and cuts a revision — :release, owner-only, and the
+          # gate lives here because the create/update branch is unknown until the identifier
+          # lookup. error! throws rather than raises, so it escapes this method's rescue.
+          authorize_klass!(segment_klass, :release)
+          # Same reassignment defect as the element path: `upload_klass` merges
+          # `created_by: current_user.id` unconditionally (segment_api.rb:147), so upgrading an
+          # existing segment template would hand its authorship to the importer.
+          segment_klass.update!(attributes.except('created_by', :created_by))
           segment_klass.create_klasses_revision(current_user)
           return { status: 'success', message: "This segment: [#{attributes['label']}] has been upgraded to the version: #{attributes['version']}!" }
         end
@@ -87,7 +181,11 @@ module Labimotion
           return { status: 'error', message: "The segment [#{attributes['label']}] is already in use." }
         else
           attributes['created_by'] = current_user.id
-          segment_klass = Labimotion::SegmentKlass.create!(attributes)
+          segment_klass = Labimotion::SegmentKlass.transaction do
+            Labimotion::SegmentKlass.create!(attributes).tap do |klz|
+              Labimotion::KlassShare.seed_owner!(klz, current_user.id)
+            end
+          end
           segment_klass.create_klasses_revision(current_user)
           return { status: 'success', message: "The segment: #{attributes['label']} has been created using version: #{attributes['version']}!" }
         end