labimotion 2.4.0.rc2 → 2.4.0.rc4

data/lib/labimotion/libs/share_resolver.rb

@@ -0,0 +1,369 @@
+# 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). Six 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. Values are KlassShare::LEVELS (10 viewer / 20 editor /
+    # 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: 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/models/concerns/template_doi.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+# TemplateDoi concern
+#
+# LabIMotion template DOI logic for the host's Doi model. The host owns the DOI
+# record and the generic DataCite plumbing (build_suffix/align_suffix, the MDS
+# client, the DataCitePublisher concern); this adds only the LabIMotion-specific
+# class methods that the gem's template DOI usecases and APIs call on ::Doi.
+#
+# The host wires it up with a single line:
+#   class Doi < ApplicationRecord
+#     include Labimotion::TemplateDoi
+#   end
+#
+# Assumes the host `dois` table has a jsonb `metadata` column (the DOI version
+# is stamped there) and that the deterministic suffix survives Doi#align_suffix
+# unchanged (reserve sets inchikey == suffix and version_count: 0 for that).
+module Labimotion
+  module TemplateDoi
+    extend ActiveSupport::Concern
+
+    # Literal namespace shared by every LabIMotion template DOI suffix.
+    LABIMOTION_DOI_NAMESPACE = 'labimotion'
+
+    # ActiveSupport::Concern extends this into the including class, so every
+    # method below becomes a class method on the host's Doi.
+    module ClassMethods
+      # Deterministic DOI suffix for a LabIMotion template klass. The same suffix
+      # is used at reserve and at release time, so both share one DOI:
+      #   element -> labimotion/element/<name>/<identifier>/<doi_version>
+      #   segment -> labimotion/segment/<element>/<identifier>/<doi_version>
+      #   dataset -> labimotion/dataset/<ols_term_id>/<identifier>/<doi_version>
+      # `<identifier>` is the first UUID group (8 hex chars) of the template's
+      # identifier/uuid, falling back to the record id. `<doi_version>` is the DOI
+      # version (see .labimotion_version_segment). Callers may pass an explicit
+      # template version; otherwise the record's current version is used.
+      def build_labimotion_suffix(record, version = nil)
+        parts = labimotion_suffix_parts(record)
+        raise ArgumentError, "unsupported template: #{record.class}" if parts.nil?
+
+        segment = labimotion_version_segment(record, version)
+        return nil if segment.blank?
+
+        segments = parts.map { |part| sanitize_doi_part(part) }.reject(&:empty?)
+        "#{segments.join('/')}/#{segment}"
+      end
+
+      # The DOI version segment for a template version. A DOI is published per major
+      # release: the .0 release opens that version (X.0 -> "X") and later minor
+      # revisions roll into the NEXT DOI (X.y, y>=1 -> "X+1"). Sub-1.0 and
+      # unversioned/blank templates map to the first DOI (v1).
+      #   0.x -> "1"   1.0 -> "1"   1.1..2.0 -> "2"   2.1..3.0 -> "3"
+      def labimotion_version_segment(record, version = nil)
+        raw = (version.presence || record.try(:version)).to_s.strip
+        parts = raw.split('.')
+        major = parts[0].to_i
+        minor = parts[1].to_i
+        return '1' if major.zero?
+        return major.to_s if minor.zero?
+
+        (major + 1).to_s
+      end
+
+      # The DOIs reserved for a LabIMotion template, in reservation order.
+      def labimotion_dois(record)
+        where(doiable_id: record.id, doiable_type: record.class.name).order(:id).to_a
+      end
+
+      # The current (most recently reserved) DOI for a template, or nil.
+      def labimotion_latest_doi(record)
+        labimotion_dois(record).last
+      end
+
+      # The DOI version (next-major integer) recorded on a reserved template DOI.
+      def labimotion_doi_version(doi)
+        doi.metadata.to_h.dig('labimotion', 'doi_version')
+      end
+
+      # Metadata stamped on a reserved template DOI so the version it represents
+      # survives on the record (used to gate reserving the next version).
+      def labimotion_doi_metadata(record, version = nil)
+        { 'labimotion' => { 'doi_version' => labimotion_version_segment(record, version) } }
+      end
+
+      # The publication metadata a released template DOI was published with.
+      # Nil while the DOI is still reserved, and for DOIs released before
+      # snapshots were kept — callers fall back to the template's current
+      # publication in both cases.
+      def labimotion_doi_publication(doi)
+        doi.metadata.to_h.dig('labimotion', 'publication')
+      end
+
+      # The DOI's metadata with the publication snapshotted into it, keeping
+      # the DOI version already stamped there. Taken at release: the template's
+      # publication keeps being edited for the next version, and this version
+      # must stop tracking those edits.
+      def labimotion_metadata_with_publication(doi, publication)
+        metadata = doi.metadata.to_h
+        # Deep-duped: the snapshot must not alias the template's publication,
+        # which goes on being edited for the next version.
+        labimotion = (metadata['labimotion'] || {}).merge('publication' => publication.deep_dup)
+        metadata.merge('labimotion' => labimotion)
+      end
+
+      def labimotion_suffix_parts(record)
+        # identifier/uuid may both be blank for a draft, which would collapse the
+        # scope (colliding across templates). Fall back to the stable record id so
+        # every template gets a unique, deterministic suffix. Resolved lazily so an
+        # unsupported record (no #id) still falls through to the ArgumentError in the
+        # caller. The identifier is shortened to its first UUID group (8 hex chars).
+        # A segment's <element> is the name of the ElementKlass it belongs to.
+        identifier = lambda do
+          raw = record.try(:identifier).presence || record.try(:uuid).presence || record.id
+          raw.to_s.split('-').first
+        end
+        case record
+        when ::Labimotion::ElementKlass
+          [LABIMOTION_DOI_NAMESPACE, 'element', record.name, identifier.call]
+        when ::Labimotion::SegmentKlass
+          [LABIMOTION_DOI_NAMESPACE, 'segment', record.element_klass&.name, identifier.call]
+        when ::Labimotion::DatasetKlass
+          [LABIMOTION_DOI_NAMESPACE, 'dataset', record.ols_term_id, identifier.call]
+        end
+      end
+
+      # Keeps a suffix segment DOI-safe: trims, collapses whitespace to hyphens and
+      # drops anything outside [A-Za-z0-9._-] (colons stripped, as elsewhere here).
+      def sanitize_doi_part(value)
+        value.to_s.strip.gsub(/\s+/, '-').gsub(/[^A-Za-z0-9._-]/, '')
+      end
+    end
+  end
+end

data/lib/labimotion/models/dataset_klass.rb

@@ -18,7 +18,7 @@ module Labimotion
     # Scope for displayed_in_list - select only necessary columns for list view
     scope :for_list_display, lambda {
       select(:id, :uuid, :label, :desc, :is_active, :version, :place, :released_at,
-             :identifier, :sync_time, :created_at, :updated_at, :ols_term_id)
+             :identifier, :sync_time, :created_at, :updated_at, :ols_term_id, :created_by)
     }
 
     def self.init_seeds

data/lib/labimotion/models/element_klass.rb

@@ -24,7 +24,7 @@ module Labimotion
     scope :for_list_display, lambda {
       select(:id, :uuid, :label, :desc, :is_active, :version, :place, :released_at,
              :identifier, :sync_time, :created_at, :updated_at, :name, :icon_name,
-             :klass_prefix, :is_generic)
+             :klass_prefix, :is_generic, :created_by)
     }
 
     def self.gen_klasses_json

data/lib/labimotion/models/klass_share.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Labimotion
+  # One user's right on one template (template-sharing.md §5). The owner row
+  # (permission_level 30) is the transferable right; the klass's `created_by` column stays
+  # immutable provenance. Deliberately NOT acts_as_paranoid, and the klass models carry no
+  # `dependent:` towards it: deleting a template must leave its shares alone, so a restored
+  # template comes back owned. Wiping the rows on delete would make restore itself a
+  # privilege escalation — the template would return owner-less and fall open to the legacy
+  # designer-wide gate.
+  class KlassShare < ApplicationRecord
+    self.table_name = :klass_shares
+
+    # `acked_at` — when the user this row *names* last acknowledged the row's current state.
+    # Written only by that user (POST /generic_klass/shares/:share_id/ack), never by the owner
+    # and never by the system: it says "seen", not "happened".
+    #
+    # Unacknowledged is `acked_at IS NULL OR acked_at < updated_at`, and that comparison is the
+    # whole mechanism (ShareResolver::UNACKNOWLEDGED_GRANTS). Nothing resets the column: any
+    # later change to the row — an upgrade to editor, an ownership transfer — moves `updated_at`
+    # past `acked_at` and re-announces itself, and a revocation is a hard delete, so the entry
+    # disappears rather than needing to be un-acked. Which is also why the *owner's* queue needs
+    # no column at all: a grant promotes the level-0 row off level 0 and a reject deletes it
+    # outright, so that queue empties itself.
+    #
+    # The corollary, and the one way to break it: the ack write must not touch `updated_at`, or
+    # the row re-announces itself for ever. The ack route writes the column directly for that
+    # reason — never through save/update.
+    #
+    # Deliberately independent of ELN's own `NoticeButton` read marker: that acknowledges a host
+    # message in the main ELN, this acknowledges a share row in the Designer, and the two answer
+    # different questions in different places.
+
+    # Strictly nested ladder (requested ⊂ viewer ⊂ editor ⊂ owner), which is what makes `>=`
+    # threshold checks valid. Spaced by ten so a future level is additive; never renumber —
+    # the one-owner-per-klass partial index freezes `permission_level = 30` into the schema.
+    #
+    # `requested` is the odd one: it grants nothing. It is how an access request is stored —
+    # a row rather than a message, because the last hop of the request loop lands on the
+    # Designer, which polls no message list, so a message nobody sees is no notification at
+    # all. As a row it survives acknowledgement, granting and rejecting become ordinary
+    # state changes on it, and the unique (klass_type, klass_id, shared_with_id) index
+    # dedupes repeat asks for free. `0 >= 10` is false, so every threshold check refuses it
+    # without a special case.
+    LEVELS = { requested: 0, viewer: 10, editor: 20, owner: 30 }.freeze
+
+    # Which account types may hold a share row. `Admin` is in the list because both seeding
+    # paths have to reach the same verdict: the seed migration is raw SQL over `created_by`
+    # and does write an owner row naming an administrator, while this validation used to
+    # refuse the runtime self-grant for the same actor and leave the template owner-less —
+    # the worse of the two, since owner-less falls back to the permanent legacy gate where
+    # any designer of the family may edit and delete it. Not hypothetical: the
+    # `backfill_klass_created_columns` migration fills a NULL `created_by` with the first
+    # system administrator, so a real population of templates is admin-created.
+    # `Group` and `DeviceDeprecated` stay out: a group is not an individual, and ELN reserves
+    # `Group` for device management.
+    SHAREABLE_USER_TYPES = %w[Person Admin].freeze
+
+    # Hash form, NOT the Rails 7 positional form: the gemspec admits ActiveRecord 6.1, where
+    # the positional form raises ArgumentError in the class body and the host fails to boot.
+    enum permission_level: LEVELS # rubocop:disable Rails/EnumSyntax
+
+    validates :klass_type, inclusion: { in: Labimotion::Constants::Klass::ALL }
+    validate :shared_with_individual
+
+    # The integer, whatever the reader: the AR enum getter answers the label string, a bare
+    # test double answers the raw integer.
+    def level
+      raw = permission_level
+      raw.is_a?(Integer) ? raw : LEVELS.fetch(raw.to_sym)
+    end
+
+    scope :for_klass, lambda { |klass_type, klass_id|
+      where(klass_type: klass_type, klass_id: klass_id)
+    }
+
+    def self.key_of(klass)
+      "#{klass.class.name.split('::').last}:#{klass.id}"
+    end
+
+    def self.owner_row_for(klass)
+      for_klass(klass.class.name.split('::').last, klass.id)
+        .find_by(permission_level: LEVELS[:owner])
+    end
+
+    # Writes the owner self-grant a fresh klass gets on every create path — bookkeeping, not
+    # enforcement, so it is unconditional but must never break the create it rides on:
+    # a host that has not migrated yet simply skips it (log only), and a concurrent duplicate
+    # means the owner row already exists, which is the goal state.
+    def self.seed_owner!(klass, user_id)
+      return unless table_exists?
+      return if owner_row_for(klass).present?
+
+      create!(klass_type: klass.class.name.split('::').last, klass_id: klass.id,
+              shared_with_id: user_id, created_by: user_id,
+              permission_level: LEVELS[:owner])
+    rescue ActiveRecord::RecordNotUnique
+      nil
+    rescue ActiveRecord::RecordInvalid => e
+      # An Admin creator no longer lands here — SHAREABLE_USER_TYPES admits it, which is the
+      # point of the allowlist. What still can: a `created_by` naming an excluded type or an
+      # account that no longer exists at all. The klass then stays owner-less on the legacy
+      # gate, logged, rather than taking the create down with it.
+      Labimotion.log_exception(e)
+      nil
+    end
+
+    private
+
+    # A share targets an individual account (SHAREABLE_USER_TYPES), never a collective one.
+    #
+    # `User.persons` survives only as the probe that this host's User *is* the ELN's STI
+    # model: it is host-owned, and its absence (an older host, a bare test double) must not
+    # turn into "reject every write". It can no longer be the query — `persons` is
+    # `where(type: 'Person')`, which is exactly the row the allowlist now has to let through.
+    # So: `respond_to?` asks whether the type column is there to be trusted, `exists?` asks
+    # the allowlist question directly, the same shape ELN's own `request_access` uses.
+    def shared_with_individual
+      return if shared_with_id.blank?
+      return unless ::User.respond_to?(:persons)
+      return if ::User.exists?(type: SHAREABLE_USER_TYPES, id: shared_with_id)
+
+      errors.add(:shared_with_id, 'must be an individual user account')
+    end
+  end
+end

data/lib/labimotion/models/segment_klass.rb

@@ -22,7 +22,7 @@ module Labimotion
     # Scope for displayed_in_list - select only necessary columns for list view
     scope :for_list_display, lambda {
       select(:id, :uuid, :label, :desc, :is_active, :version, :place, :released_at,
-             :identifier, :sync_time, :created_at, :updated_at, :element_klass_id)
+             :identifier, :sync_time, :created_at, :updated_at, :element_klass_id, :created_by)
     }
 
     def self.gen_klasses_json