labimotion 2.3.0 → 2.4.0.rc11

data/lib/labimotion/apis/klass_share_api.rb

@@ -0,0 +1,648 @@
+# frozen_string_literal: true
+
+require 'time' # Time#iso8601, for the share_activity token below
+require 'labimotion/version'
+
+module Labimotion
+  # Share management for generic templates (template-sharing.md §7). Its own API class, not
+  # more namespaces in GenericKlassAPI, so the spec harness can load and mount it alone.
+  #
+  # Grant and level-change accept viewer/editor/maintainer only: the owner level never moves through
+  # these routes. It moves through transfer_ownership, an update of the single owner row, so
+  # the one-owner-per-klass invariant holds at every instant and the handover is auditable.
+  #
+  # request_access is the one route a non-holder may call, and it writes the one level the
+  # others refuse: 0, which grants nothing and only records the ask.
+  #
+  # Metrics/ClassLength is disabled for the same reason Metrics/BlockLength is on the helpers
+  # below: almost none of this is logic. It is Grape route DSL — a `desc`, a `params` block and
+  # a body per endpoint — and the cop counts every declaration and rescue clause as a class
+  # line. Splitting the routes across classes to satisfy it would scatter one coherent surface
+  # (`/generic_klass/shares…`) over several files.
+  class KlassShareAPI < Grape::API # rubocop:disable Metrics/ClassLength
+    helpers Labimotion::GenericHelpers
+
+    # How many rows one batch read may ask for. The poller is the caller, so the bound is about
+    # the payload rather than the client's patience: fifty klass entities carry fifty
+    # properties_templates, which is already a large response, and a Designer whose diff names
+    # more keys than that has effectively had its whole grid change — it can fall back to the
+    # list endpoint it was trying to avoid. Refused rather than truncated: a silently short
+    # answer would leave the client believing the missing keys were deleted.
+    MAX_ROW_KEYS = 50
+
+    # rubocop:disable Metrics/BlockLength
+    helpers do
+      def find_share!(share_id)
+        row = Labimotion::KlassShare.find_by(id: share_id)
+        error!('Share is invalid. Please refresh.', 404) if row.nil?
+        row
+      end
+
+      def share_klass!(row)
+        fetch_klass(row.klass_type, row.klass_id)
+      end
+
+      # The owner row is undeletable and undowngradeable by construction: removing it leaves
+      # the klass owner-less, which falls open to the legacy designer-wide gate. 409 pointing
+      # at transfer_ownership, mirroring Docs — an owner transfers before stepping off.
+      def guard_owner_row!(row)
+        return unless row.level == Labimotion::KlassShare::LEVELS[:owner]
+
+        error!({ mc: Labimotion::GenericHelpers::OWNER_ROW_MC,
+                 msg: 'The owner cannot be removed or downgraded. ' \
+                      'Transfer ownership first (transfer_ownership).' }, 409)
+      end
+
+      # Person-only, deliberately narrower than the model's allowlist
+      # (KlassShare::SHAREABLE_USER_TYPES, which also admits Admin). The model has to accept
+      # the admin owner rows the seed paths write; nothing should mint a *new* one here. A
+      # grant comes from the Share modal's Person picker, and transfer_ownership is the route
+      # that moves a template *off* an admin — it checks the target, never the current owner,
+      # so an admin-owned template still transfers away under this rule.
+      #
+      # Validated here as well as on the model, so the refusal is a clean 404 naming the id
+      # rather than a validation error.
+      def person!(user_id)
+        scope = ::User.respond_to?(:persons) ? ::User.persons : ::User
+        person = scope.find_by(id: user_id)
+        error!("User #{user_id} is not a valid share target.", 404) if person.nil?
+        person
+      end
+
+      # A caller who already holds viewer/editor/owner has nothing to request. 409 rather
+      # than a silent success: the only way to get here is a grid that has not seen the grant
+      # yet, and the client needs to know to refresh rather than to show "asked".
+      def guard_access_held!(row)
+        return if row.level < Labimotion::KlassShare::LEVELS[:viewer]
+
+        error!({ mc: Labimotion::GenericHelpers::ACCESS_ALREADY_HELD_MC,
+                 msg: 'You already have access to this template. Reload the list.' }, 409)
+      end
+
+      # Two lists, not one. A level-0 row is somebody *waiting* for access, and listing them
+      # under "People with access" says the opposite of what they are. `shares` keeps its
+      # contents and owner-first ordering for everything that confers access, the owner row
+      # included — the modal filters that one out itself.
+      #
+      # Both lists go to anyone who may `:read` the template, so viewers and editors see
+      # other people's pending requests. Intended: the request is a fact about the template,
+      # and hiding it would need a second authorization pass over a list this small.
+      def represent_shares(klz)
+        rows = Labimotion::KlassShare.for_klass(klz.class.name.split('::').last, klz.id).to_a
+        users = Labimotion::OwnerResolver.map_for_ids(rows.map(&:shared_with_id))
+        owner_row = rows.find { |row| row.level == Labimotion::KlassShare::LEVELS[:owner] }
+        granted, requested = rows.partition do |row|
+          row.level >= Labimotion::KlassShare::LEVELS[:viewer]
+        end
+        {
+          owner: owner_row && Labimotion::KlassShareEntity.represent(owner_row, users: users),
+          shares: Labimotion::KlassShareEntity.represent(
+            granted.sort_by { |row| -row.level }, users: users
+          ),
+          # Oldest ask first: the modal is a queue, and whoever waited longest reads first.
+          requests: Labimotion::KlassShareEntity.represent(
+            requested.sort_by(&:id), users: users
+          )
+        }
+      end
+
+      # The two inbox queues in wire form. Two shapes rather than one entity, because the two
+      # queues answer different questions: a request names the person *waiting* (shared_with_id)
+      # and when they asked, a grant names the person who *granted* it (created_by), what they
+      # granted, and when it last moved. One shared shape would have meant a `user` field whose
+      # meaning flipped with the list it happened to be in.
+      #
+      # Both bulk resolutions happen here, once over both queues together: the klass labels
+      # (grouped by type) and the user names (one query), never a lookup per row — this route
+      # sits on the same once-a-minute poll tick as share_activity.
+      def represent_inbox(inbox)
+        labels = klass_labels(inbox[:requests] + inbox[:grants])
+        users = Labimotion::OwnerResolver.map_for_ids(
+          inbox[:requests].map(&:shared_with_id) + inbox[:grants].map(&:created_by)
+        )
+        { requests: request_entries(inbox[:requests], labels, users),
+          grants: grant_entries(inbox[:grants], labels, users) }
+      end
+
+      # Oldest ask first: the owner's queue is a queue, and whoever waited longest reads first —
+      # the same ordering the Share modal's `requests` list uses.
+      def request_entries(rows, labels, users)
+        inbox_entries(rows.sort_by(&:id), labels) do |row, entry|
+          entry.merge(user: inbox_user(row.shared_with_id, users),
+                      requested_at: row.created_at&.iso8601)
+        end
+      end
+
+      # Newest change first: this half is an announcement list, so the freshest news reads first.
+      # `changed_at` is `updated_at`, not `created_at`, because updated_at is what `acked_at` is
+      # compared against — the entry describes the row's *current* state, which an upgrade or a
+      # transfer moves long after the row was first written. Ties broken by id so the order is
+      # deterministic when a batch grant stamps several rows in the same instant.
+      def grant_entries(rows, labels, users)
+        ordered = rows.sort_by { |row| [row.updated_at, row.id] }.reverse
+        inbox_entries(ordered, labels) do |row, entry|
+          entry.merge(permission: level_label(row), user: inbox_user(row.created_by, users),
+                      changed_at: row.updated_at&.iso8601)
+        end
+      end
+
+      # A row whose template cannot be resolved is dropped rather than sent with a null label:
+      # every entry exists to be clicked through to a grid row, and a deleted template has none
+      # (acts_as_paranoid puts a soft-deleted one outside the default scope by itself). Nothing
+      # is lost by dropping it — the share row survives the delete, since KlassShare carries no
+      # `dependent:` so a restored template comes back owned, and neither created_at nor
+      # updated_at moved, so the entry reappears exactly as it was.
+      def inbox_entries(rows, labels)
+        rows.filter_map do |row|
+          key = "#{row.klass_type}:#{row.klass_id}"
+          next if labels[key].nil?
+
+          yield(row, { share_id: row.id, klass_type: row.klass_type, klass_id: row.klass_id,
+                       klass_label: labels[key] })
+        end
+      end
+
+      # One query per klass type present in the two queues, never one per row. `pluck` rather
+      # than loading records: an ElementKlass carries its whole properties_template, and all the
+      # inbox wants is a label.
+      def klass_labels(rows)
+        rows.group_by(&:klass_type).each_with_object({}) do |(type, group), map|
+          "Labimotion::#{type}".constantize
+                               .where(id: group.map(&:klass_id).uniq)
+                               .pluck(:id, :label)
+                               .each { |id, label| map["#{type}:#{id}"] = label }
+        end
+      end
+
+      # No `state` field, unlike KlassShareEntity's user block: that one renders a live
+      # collaborator list, where a departed account has to grey out. The inbox names the other
+      # party of something that already happened, and their leaving since does not change it.
+      def inbox_user(user_id, users)
+        resolved = users[user_id]
+        { id: user_id, name: resolved&.name, name_abbreviation: resolved&.name_abbreviation }
+      end
+
+      def level_label(row)
+        value = row.permission_level
+        value.is_a?(Integer) ? Labimotion::KlassShare::LEVELS.key(value)&.to_s : value.to_s
+      end
+
+      # Wire form of one key's change token: `"<row count>|<newest updated_at>"`, in the same
+      # millisecond precision `latest` uses, because two changes inside one second have to be
+      # two different digests. Opaque to the client, which compares the whole string for
+      # inequality and never parses it — so the separator and the field order are free to change
+      # as long as they change for every key at once.
+      def share_digests(digests)
+        (digests || {}).each_with_object({}) do |(key, digest), map|
+          map[key] = "#{digest[:count]}|#{digest[:latest]&.iso8601(3)}"
+        end
+      end
+
+      # `"KlassType:id"` — the format KlassShare.key_of produces and share_activity's digest map
+      # is keyed by, so a key the client saw move is directly the argument that re-reads it.
+      # Malformed keys are refused rather than guessed at or dropped: a key nobody meant is a
+      # client bug, and skipping it silently would surface much later as a grid row that never
+      # refreshes. The cap is checked on what was *asked for*, before de-duplication, so a poll
+      # cannot buy itself a bigger payload by repeating keys.
+      def parse_row_keys!(keys)
+        if keys.size > Labimotion::KlassShareAPI::MAX_ROW_KEYS
+          error!({ mc: 'se00',
+                   msg: "At most #{Labimotion::KlassShareAPI::MAX_ROW_KEYS} keys per request." }, 400)
+        end
+
+        keys.uniq.map do |key|
+          type, id = key.to_s.split(':', 2)
+          unless Labimotion::Constants::Klass::ALL.include?(type) && id.to_s.match?(/\A[1-9]\d*\z/)
+            error!({ mc: 'se00', msg: "Malformed key: #{key}" }, 400)
+          end
+
+          [type, id.to_i]
+        end
+      end
+
+      # One query per klass type, never one per key — the diff the poller hands over can name
+      # all three types and fifty ids, and this route sits on the same once-a-minute path as
+      # share_activity.
+      #
+      # A key whose record is gone is skipped rather than raised on: a template deleted between
+      # the poll and the read is an ordinary race (and acts_as_paranoid puts a soft-deleted one
+      # outside the default scope by itself), and the client's own row goes away on its next
+      # natural refresh.
+      def batch_rows(pairs)
+        pairs.group_by(&:first).each_with_object({ keys: [], data: [] }) do |(type, group), acc|
+          records = row_records(type, group.map(&:last))
+          next if records.empty?
+
+          acc[:keys].concat(records.map { |record| "#{type}:#{record.id}" })
+          acc[:data].concat(Array(represent_rows(type, records)))
+        end
+      end
+
+      def row_records(type, ids)
+        scope = "Labimotion::#{type}".constantize.where(id: ids)
+        # SegmentKlassEntity nests ElementKlassEntity, so the parent is read either way; ask for
+        # it in this query rather than one per row, exactly as list_segment_klass does.
+        scope = scope.preload(:element_klass) if type == Labimotion::Constants::Klass::SEGMENT
+        scope.to_a
+      end
+
+      # The options list_element_klass / list_segment_klass / list_dataset_klass pass, and no
+      # others: "same shape as the list" *is* the contract here. The client drops one of these
+      # into a grid row, and `owner`, `can_write` … `can_manage`, `current_user_permission` and
+      # `pending_request_count` all have to keep meaning what they meant in the list — the
+      # library reads an absent capability field as permissive, so a row missing them would come
+      # back looking editable to a viewer.
+      #
+      # `displayed_in_list: false` is what the three Designer grids get. Note the direction:
+      # DISPLAYED_IN_LIST_CONDITION is `unless:`, so false is the *full* payload,
+      # properties_template included — a row refresh that dropped the template body would be no
+      # use to the Work Area this route exists to keep alive.
+      #
+      # For segments the parent element klasses join the owners map and the share context, the
+      # same way list_segment_klass does it: Grape hands serialization options down into nested
+      # entities, so the nested ElementKlassEntity resolves an owner too, and without them every
+      # nested row falls back to a user query of its own.
+      def represent_rows(type, records)
+        related = records
+        related += records.map(&:element_klass) if type == Labimotion::Constants::Klass::SEGMENT
+        related = related.compact
+        "Labimotion::#{type}Entity".constantize.represent(
+          records,
+          displayed_in_list: false, with_ownership: true,
+          owners: Labimotion::OwnerResolver.map_for(related),
+          share_context: Labimotion::ShareResolver.context_for(related, current_user)
+        )
+      end
+    end
+    # rubocop:enable Metrics/BlockLength
+
+    resource :generic_klass do
+      namespace :shares do
+        desc 'list the shares of one template'
+        params do
+          requires :klass, type: String, desc: 'Klass', values: Labimotion::Constants::Klass::ALL
+          requires :id, type: Integer, desc: 'Klass ID'
+        end
+        get do
+          klz = fetch_klass(params[:klass], params[:id])
+          authorize_klass!(klz, :read)
+          { mc: 'ss00' }.merge(represent_shares(klz))
+        rescue StandardError => e
+          Labimotion.log_exception(e, current_user)
+          { mc: 'se00', msg: e.message }
+        end
+
+        desc 'grant viewer/editor/maintainer access to users (upsert)'
+        params do
+          requires :klass, type: String, desc: 'Klass', values: Labimotion::Constants::Klass::ALL
+          requires :id, type: Integer, desc: 'Klass ID'
+          # Grape's array-of-type coercion syntax, not a redundant constructor.
+          # rubocop:disable Style/RedundantArrayConstructor
+          requires :user_ids, type: Array[Integer], desc: 'users to share with (Persons only)'
+          # rubocop:enable Style/RedundantArrayConstructor
+          # Literal 10/20/25 (viewer/editor/maintainer), not KlassShare::LEVELS: params blocks
+          # run while the routes are built, and referencing the ActiveRecord model there would
+          # force it to load in any process that only mounts the API. Owner (30) is absent on
+          # purpose.
+          requires :permission_level, type: Integer, desc: 'viewer, editor or maintainer', values: [10, 20, 25]
+        end
+        post do
+          klz = fetch_klass(params[:klass], params[:id])
+          authorize_klass!(klz, :manage)
+          # Resolve and guard every target before writing anything: one bad id in the batch
+          # must refuse the whole grant, not leave the first half written.
+          rows = params[:user_ids].uniq.map do |user_id|
+            person!(user_id)
+            row = Labimotion::KlassShare.find_or_initialize_by(
+              klass_type: params[:klass], klass_id: klz.id, shared_with_id: user_id
+            )
+            # Re-granting over the owner's own row must not silently demote the owner.
+            guard_owner_row!(row) unless row.new_record?
+            row
+          end
+          Labimotion::KlassShare.transaction do
+            rows.each do |row|
+              row.created_by = current_user.id
+              row.permission_level = params[:permission_level]
+              row.save!
+            end
+          end
+          # After the commit, and fire-and-forget: ShareNotifier rescues
+          # internally, so an undeliverable toast can never turn a written
+          # grant into an se00 (labimotion#255 — moved in from the host).
+          Labimotion::ShareNotifier.grant(
+            klass: klz, actor: current_user, user_ids: params[:user_ids].uniq,
+            level: { 10 => 'viewer', 20 => 'editor', 25 => 'maintainer' }.fetch(params[:permission_level])
+          )
+          { mc: 'ss00' }.merge(represent_shares(klz))
+        rescue StandardError => e
+          Labimotion.log_exception(e, current_user)
+          { mc: 'se00', msg: e.message }
+        end
+
+        desc 'change the level of one share (viewer/editor/maintainer only)'
+        params do
+          requires :share_id, type: Integer, desc: 'Share ID'
+          # Literal 10/20/25 (viewer/editor/maintainer), not KlassShare::LEVELS: params blocks
+          # run while the routes are built, and referencing the ActiveRecord model there would
+          # force it to load in any process that only mounts the API. Owner (30) is absent on
+          # purpose.
+          requires :permission_level, type: Integer, desc: 'viewer, editor or maintainer', values: [10, 20, 25]
+        end
+        put ':share_id' do
+          row = find_share!(params[:share_id])
+          klz = share_klass!(row)
+          authorize_klass!(klz, :manage)
+          guard_owner_row!(row)
+          row.update!(permission_level: params[:permission_level], created_by: current_user.id)
+          # No notification here, deliberately: the Share modal's level changes
+          # ride the POST upsert above (which announces them), and this route
+          # has no library caller — matching the host layer it replaced, which
+          # never notified for it either.
+          { mc: 'ss00' }.merge(represent_shares(klz))
+        rescue StandardError => e
+          Labimotion.log_exception(e, current_user)
+          { mc: 'se00', msg: e.message }
+        end
+
+        desc 'revoke one share'
+        params do
+          requires :share_id, type: Integer, desc: 'Share ID'
+        end
+        delete ':share_id' do
+          row = find_share!(params[:share_id])
+          klz = share_klass!(row)
+          authorize_klass!(klz, :manage)
+          guard_owner_row!(row)
+          # Revoking on an ElementKlass leaves explicit SegmentKlass shares standing —
+          # inheritance is highest-wins, not a substitute — and revocations do not notify.
+          row.destroy!
+          { mc: 'ss00' }.merge(represent_shares(klz))
+        rescue StandardError => e
+          Labimotion.log_exception(e, current_user)
+          { mc: 'se00', msg: e.message }
+        end
+
+        # The requester's half of the inbox, and the only write in this class that is not an
+        # owner's: marking one grant seen. Idempotent — re-acking simply re-stamps the column,
+        # and the row stays hidden either way.
+        desc 'mark one share row seen (self only)'
+        params do
+          requires :share_id, type: Integer, desc: 'Share ID'
+        end
+        post ':share_id/ack' do
+          row = find_share!(params[:share_id])
+          # Self only. Acking is the person the row *names* saying "seen", so nobody may say it
+          # on their behalf — not the owner, not an administrator, and authorize_klass! is
+          # therefore the wrong question entirely: holding :manage on the template does not make
+          # somebody else's grant yours to acknowledge.
+          #
+          # 404 with find_share!'s own message rather than 403: the inbox is the only place a
+          # share id reaches this user, so a row that does not name them is indistinguishable
+          # from one that does not exist, and a 403 would confirm that somebody else's share
+          # sits at that id.
+          error!('Share is invalid. Please refresh.', 404) unless row.shared_with_id == current_user.id
+          # update_column, NOT update! — deliberate, and the whole reason this is not a one-liner.
+          # `updated_at` is the other half of the unacknowledged comparison
+          # (acked_at IS NULL OR acked_at < updated_at), so an ack that bumped it would land
+          # acked_at and updated_at on the same write and leave the row announcing itself for
+          # ever. update_column writes the one column and skips the timestamp entirely, which
+          # also keeps the row out of share_activity's change token: marking a message read is
+          # not a change to anybody's sharing, and it must not make every other Designer session
+          # re-read the grid row.
+          #
+          # `Time.now.utc`, not `Time.current`: this is a machine timestamp whose only job is to
+          # be compared against `updated_at`, and that is exactly the clock and zone ActiveRecord
+          # itself writes `updated_at` from (default_timezone :utc). It also keeps the file free
+          # of ActiveSupport's zone machinery, which the gem's own spec process does not boot.
+          row.update_column(:acked_at, Time.now.utc) # rubocop:disable Rails/SkipsModelValidations
+          # 200, not Grape's default 201 on a POST: nothing was created.
+          status 200
+          { mc: 'ss00' }
+        rescue StandardError => e
+          Labimotion.log_exception(e, current_user)
+          { mc: 'se00', msg: e.message }
+        end
+      end
+
+      # What the Designer polls to learn that its share state moved (§7), and the whole of what
+      # it needs: two aggregates over the share rows involving the caller. It used to ask the
+      # *host* instead — a poll of `/api/v1/messages/list?is_ack=0` — which could not answer
+      # this question: that list carries every kind of notification and the library cannot name
+      # the host's channels to filter it, so an unrelated spectra message refreshed the grid; it
+      # is a host route no embedder is obliged to mount, and the library's only reach outside
+      # gem-owned API surface; and reading it acknowledges message rows as a side effect. The
+      # question is about klass_shares, so it is answered here, from data the gem already holds.
+      #
+      # Authentication only, and deliberately no further gate. authorize_klass! cannot apply —
+      # there is no single klass in the question — and neither can authenticate_admin!, which
+      # needs a family. What makes that safe is the payload: a row count and a timestamp over
+      # the caller's *own* involvement, naming no template, no user and no level, and disclosing
+      # nothing about anybody else's sharing. A gate here would refuse the very callers the
+      # route exists for — a grantee holds no designer right and owns nothing to authorize on.
+      namespace :share_activity do
+        desc 'change token for the share rows involving the current user'
+        get do
+          activity = Labimotion::ShareResolver.activity_for(current_user)
+          # `latest` may move *backwards*: a revocation is a hard delete, so the newest
+          # surviving row can be older than the one that just went away. The client therefore
+          # compares the pair for inequality in either direction and never as "newer than" —
+          # a timestamp cursor would stop detecting revocations. Milliseconds, so that two
+          # changes within the same second are still two different tokens.
+          #
+          # `digests` is the same token taken per klass key, and it is what lets the client
+          # stop reloading its whole grid: it diffs the map and re-reads only the keys whose
+          # digest changed, appeared or vanished, through `GET /generic_klass/rows` below. Same
+          # inequality-in-either-direction rule, and it matters more here — a revoked template's
+          # key drops out of the map entirely, and a key's `count`/`latest` both move down.
+          # `count` and `latest` stay: they are the cheap early-out, and a client that only
+          # wants "did anything change" need not walk the map at all.
+          { mc: 'ss00', count: activity[:count], latest: activity[:latest]&.iso8601(3),
+            digests: share_digests(activity[:digests]) }
+        rescue StandardError => e
+          Labimotion.log_exception(e, current_user)
+          { mc: 'se00', msg: e.message }
+        end
+      end
+
+      # The Designer's share inbox (§7): the two queues that make the request loop's last hop
+      # visible to somebody. The owner gets what is waiting on their templates; the requester
+      # gets the grants nobody has told them about — until now the grant landed as a host
+      # message on a page the Designer does not watch, so the person who asked was never told.
+      #
+      # Polled on the same tick as share_activity above: one timer, two endpoints. Which rows go
+      # into each queue is ShareResolver's question and its spec's; this route's job is the wire
+      # shape, and the two bulk resolutions (klass labels, user names) that turn rows into lines
+      # somebody can read.
+      #
+      # Authentication only, and deliberately no further gate — the same reasoning as
+      # share_activity above, so nobody should "fix" it here either. authorize_klass! has no
+      # single klass to take and authenticate_admin! no family, and what makes it safe is that
+      # every row returned either names the caller or sits on a template the caller holds the
+      # owner row on. A gate would refuse the very callers the route exists for: a grantee holds
+      # no designer right and owns nothing to authorize on.
+      namespace :share_inbox do
+        desc "the current user's two share queues: requests to answer, grants to acknowledge"
+        get do
+          inbox = Labimotion::ShareResolver.inbox_for(current_user)
+          { mc: 'ss00' }.merge(represent_inbox(inbox))
+        rescue StandardError => e
+          Labimotion.log_exception(e, current_user)
+          { mc: 'se00', msg: e.message, requests: [], grants: [] }
+        end
+      end
+
+      # The other half of the poller's contract, and the reason it exists: knowing *which*
+      # templates moved is only useful if a client can re-read those rows alone. Every entry is
+      # what the Designer list endpoints return for the same record — same entity, the same
+      # `with_ownership`, `owners:` and `share_context:` options — so a row can be dropped
+      # straight into the grid and every capability field still means what it meant in the list.
+      #
+      # It lives here rather than beside `GET /generic_klass/fetch`, which it superficially
+      # resembles, for the reason this whole class exists: `fetch` represents with neither
+      # `share_context` nor `with_ownership`, so a row read through it carries no `owner`, no
+      # `can_*` and no `current_user_permission` — and the library reads absent capability
+      # fields as permissive (that is how an un-upgraded gem stays usable), so patching a grid
+      # row from `fetch` would quietly turn a viewer's row editable. Widening `fetch` instead
+      # would change a payload other callers already depend on.
+      #
+      # Authorization: deliberately none, matching the list endpoints this mirrors. Those are
+      # ungated by decision — every designer lists every template, and it is the *actions* that
+      # gate — and a row read has to answer to exactly the same callers, including the grantee
+      # who holds no designer right at all. What constrains the caller is inside the payload:
+      # the capability booleans and `current_user_permission` are resolved for *this* user, and
+      # every mutating route re-checks with authorize_klass! regardless. So do not "fix" the
+      # missing gate here: it would break the poller for the users sharing exists for, without
+      # protecting anything the list endpoints do not already disclose.
+      namespace :rows do
+        desc 'batch-read grid rows for the keys share_activity flagged'
+        params do
+          # `?keys[]=ElementKlass:12&keys[]=SegmentKlass:3` — Grape's array-of-type coercion
+          # syntax, not a redundant constructor.
+          # rubocop:disable Style/RedundantArrayConstructor
+          requires :keys, type: Array[String], desc: '"KlassType:id" keys, at most 50'
+          # rubocop:enable Style/RedundantArrayConstructor
+        end
+        get do
+          rows = batch_rows(parse_row_keys!(params[:keys]))
+          # `keys` runs parallel to `data`, and is not decoration: the klass entities carry no
+          # type field, so an id alone cannot say whether a row is ElementKlass:12 or
+          # DatasetKlass:12. It is also how the client learns which requested keys were skipped
+          # — set-difference the two — without having to guess from the array's length.
+          { mc: 'ss00', data: rows[:data], keys: rows[:keys] }
+        rescue StandardError => e
+          Labimotion.log_exception(e, current_user)
+          { mc: 'se00', msg: e.message, data: [], keys: [] }
+        end
+      end
+
+      namespace :transfer_ownership do
+        desc 'hand the owner row to another user'
+        params do
+          requires :klass, type: String, desc: 'Klass', values: Labimotion::Constants::Klass::ALL
+          requires :id, type: Integer, desc: 'Klass ID'
+          requires :user_id, type: Integer, desc: 'the new owner (a Person)'
+        end
+        post do
+          klz = fetch_klass(params[:klass], params[:id])
+          # :manage admits the owner and the administrator (implicit super owner) — the
+          # latter is how a template whose owner departed gets a new one. On an owner-less
+          # template :manage falls back to the legacy designer gate, which makes this route
+          # double as adoption: assigning a first owner creates the row.
+          authorize_klass!(klz, :manage)
+          person!(params[:user_id])
+          owner_row = Labimotion::KlassShare.owner_row_for(klz)
+          Labimotion::KlassShare.transaction do
+            # The new owner may already hold a viewer/editor row; the unique (klass, user)
+            # index would collide with the handover, so that share is absorbed into the
+            # ownership first.
+            existing = Labimotion::KlassShare.for_klass(params[:klass], klz.id).to_a.find do |row|
+              row.shared_with_id == params[:user_id] &&
+                row.level != Labimotion::KlassShare::LEVELS[:owner]
+            end
+            existing&.destroy!
+            if owner_row.nil?
+              Labimotion::KlassShare.create!(
+                klass_type: params[:klass], klass_id: klz.id,
+                shared_with_id: params[:user_id], created_by: current_user.id,
+                permission_level: Labimotion::KlassShare::LEVELS[:owner]
+              )
+            else
+              # An UPDATE, not delete-and-insert: the one-owner partial index stays satisfied
+              # throughout, and created_by records who performed the handover.
+              owner_row.update!(shared_with_id: params[:user_id], created_by: current_user.id)
+            end
+          end
+          # After the commit; rescues internally, never fails the transfer, and
+          # drops the actor — a self-transfer announces nothing (#255).
+          Labimotion::ShareNotifier.transfer(klass: klz, actor: current_user,
+                                             user_id: params[:user_id])
+          { mc: 'ss00' }.merge(represent_shares(klz))
+        rescue StandardError => e
+          Labimotion.log_exception(e, current_user)
+          { mc: 'se00', msg: e.message }
+        end
+      end
+
+      # The requester's own route, and the only one that writes a level-0 row. `POST /shares`
+      # cannot serve them: it is gated `:manage`, which only the owner and the administrator
+      # hold, and the entire premise of a request is that the caller holds nothing.
+      #
+      # There is no matching "grant" or "reject" route, on purpose. Granting is `POST /shares`
+      # unchanged — its find_or_initialize_by lands on this very row and lifts it to 10/20,
+      # and guard_owner_row! only protects level 30 — and rejecting is `DELETE /shares/:id`,
+      # a hard delete because KlassShare is deliberately not acts_as_paranoid. So "no" does
+      # not stick: the row's disappearance makes the requester askable again, and there is no
+      # "stop asking". Accepted — a tombstone would contradict the hard delete.
+      namespace :request_access do
+        desc 'ask the owner for access to one template (self, level 0, idempotent)'
+        params do
+          requires :klass, type: String, desc: 'Klass', values: Labimotion::Constants::Klass::ALL
+          requires :id, type: Integer, desc: 'Klass ID'
+        end
+        post do
+          klz = fetch_klass(params[:klass], params[:id])
+          # Deliberately NOT authorize_klass!(klz, :read): `:read` demands level >= 10 and a
+          # requester has no level at all, so the share gate would refuse every caller this
+          # route exists for. The legacy family designer right gates it instead — the grid
+          # the request is made from is behind that same right, so everyone who can see the
+          # template well enough to ask about it passes here, and nobody else does.
+          authenticate_admin!(klass_family(klz))
+          # Self only, level 0 only. Neither the target user nor the level is a parameter, so
+          # no shape of this request escalates anybody: the worst a caller can do is ask.
+          row = Labimotion::KlassShare.find_or_initialize_by(
+            klass_type: params[:klass], klass_id: klz.id, shared_with_id: current_user.id
+          )
+          created = row.new_record?
+          guard_access_held!(row) unless created
+          if created
+            row.created_by = current_user.id
+            row.permission_level = Labimotion::KlassShare::LEVELS[:requested]
+            row.save!
+          end
+          # `created` is the notify switch, and the server owns it outright now
+          # (labimotion#255): the unique index dedupes rows, not messages, so
+          # only the ask that wrote the row pings the owner — ten asks are one
+          # toast. ShareNotifier rescues internally; an undeliverable ping
+          # never fails the request, whose success is the row.
+          Labimotion::ShareNotifier.request(klass: klz, actor: current_user) if created
+          # 200 either way, not Grape's default 201 on the create: the ping
+          # decision is `created` in the body, and a client that read it off
+          # the status code would be reading the wrong thing. One status keeps
+          # that unambiguous.
+          status 200
+          { mc: 'ss00', created: created }
+        rescue ActiveRecord::RecordNotUnique
+          # Two concurrent asks collide on the unique (klass, user) index. The row exists
+          # either way, which is the goal state, and the insert that won already earned the
+          # ping — so this one answers created: false rather than 500.
+          status 200
+          { mc: 'ss00', created: false }
+        rescue StandardError => e
+          Labimotion.log_exception(e, current_user)
+          { mc: 'se00', msg: e.message }
+        end
+      end
+    end
+  end
+end