slk 0.9.0 → 0.11.0

data/lib/slk/services/sent_changes.rb

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+require 'bigdecimal'
+
+module Slk
+  module Services
+    # Stateless diff of watched sent conversations. Search discovers what to
+    # watch; exact-ts history/replies determine what actually changed.
+    # Orchestration spans workspace watch sets, thread diffs and output windows.
+    # rubocop:disable Metrics/ClassLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/MethodLength
+    class SentChanges
+      Change = Data.define(:conversation, :new_timestamps, :new_count, :new_from_others)
+      Conversation = SentConversations::Conversation
+      OPTIONAL_SUBSCRIPTION_ERRORS = %i[missing_scope not_allowed_token_type unknown_method].freeze
+
+      # rubocop:disable Metrics/ParameterLists
+      def initialize(runner:, since:, context: 2, max: 200, before: 5, after_minutes: 30)
+        @runner = runner
+        @since = since
+        @since_ts = Support::CheckInTime.timestamp(since)
+        @context = context
+        @max = max
+        @before = before
+        @after_minutes = after_minutes
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      def collect(entries, workspaces:)
+        groups = entries.group_by { |workspace, hit| [workspace.name, hit.channel_id] }
+        changes = workspaces.flat_map { |workspace| collect_workspace(workspace, groups) }
+        changes.sort_by do |change|
+          conversation = change.conversation
+          # Put the most recently active conversation last. Trailing identity
+          # keys make ties deterministic across platforms (including Windows).
+          [BigDecimal(conversation.messages.last.ts), conversation.workspace.name.to_s,
+           conversation.channel_id.to_s, conversation.thread_ts.to_s]
+        end
+      end
+
+      private
+
+      def collect_workspace(workspace, groups)
+        @workspace = workspace
+        @api = @runner.conversations_api(workspace.name)
+        @self_id = self_id(workspace, groups)
+        local = groups.select { |(name, _id), _hits| name == workspace.name }
+        changed_threads = local.flat_map { |(_name, _id), entries| thread_changes(entries.map(&:last)) }
+        changed_threads.concat(subscribed_changes(changed_threads, local))
+        claimed = changed_threads.flat_map { |change| change.conversation.messages.map(&:ts) }.to_h { |ts| [ts, true] }
+        other = local.flat_map do |(_name, _id), entries|
+          hits = entries.map(&:last)
+          hits.first.dm? ? dm_changes(hits, claimed) : channel_changes(hits, claimed)
+        end
+        changed_threads + other
+      end
+
+      def self_id(workspace, groups)
+        entries = groups.find { |(name, _id), rows| name == workspace.name && rows.any? }&.last
+        hit = entries&.first&.last
+        return hit.user_id if hit&.user_id.to_s.match?(/\A[UW][A-Z0-9]+\z/i)
+
+        cached = @runner.cache_store.get_meta(workspace.name, 'self_user_id')
+        return cached if cached
+
+        id = @runner.client_api(workspace.name).auth_test['user_id']
+        raise ApiError, "Cannot identify sender in #{workspace.name}" unless id
+
+        @runner.cache_store.set_meta(workspace.name, 'self_user_id', id)
+        id
+      end
+
+      def thread_changes(hits)
+        metadata = root_metadata(hits)
+        hits.map { |hit| [hit.thread_ts || hit.ts, hit] }.uniq(&:first).filter_map do |root, seed|
+          parent = metadata[root]
+          next if parent && !thread_active?(parent)
+
+          thread_change(seed, root, full_first: parent && parent['latest_reply'])
+        end
+      end
+
+      # Fetch the watched top-level parents in one paginated history scan per
+      # channel. Search often omits reply_count; history has latest_reply.
+      def root_metadata(hits)
+        roots = hits.select { |hit| top_level?(hit) }.map(&:ts).uniq
+        return {} if roots.empty?
+
+        wanted = roots.to_h { |root| [root, true] }
+        found = {}
+        cursor = nil
+        loop do
+          response = @api.history(channel: hits.first.channel_id,
+                                  oldest: roots.min_by { |root| BigDecimal(root) }, inclusive: true,
+                                  limit: 200, cursor: cursor)
+          response.fetch('messages', []).each do |message|
+            found[message['ts']] = message if wanted[message['ts']]
+          end
+          break if found.size == wanted.size || !response['has_more']
+
+          cursor = next_cursor!(response, cursor, :history)
+        end
+        found
+      end
+
+      def thread_active?(parent)
+        latest = parent['latest_reply']
+        return newer?(latest) if latest
+
+        parent['reply_count'].to_i.positive?
+      end
+
+      def thread_change(seed, root, require_participation: false, full_first: false)
+        full = page_through(:replies, channel: seed.channel_id, timestamp: root) if full_first
+        recent = full || page_through(:replies, channel: seed.channel_id, timestamp: root, oldest: @since_ts)
+        fresh = after_cutoff(recent)
+        # A new top-level post without replies belongs in its channel/DM
+        # window, not in a synthetic one-message thread.
+        return if fresh.none? { |row| row['ts'] != root }
+
+        full ||= page_through(:replies, channel: seed.channel_id, timestamp: root)
+        return if require_participation && full.none? { |row| row['user'] == @self_id }
+
+        context = previous_messages(full, parent_ts: root)
+        change(seed, 'thread', root, fresh, context)
+      rescue ApiError => e
+        raise unless e.code == :thread_not_found
+      end
+
+      # Slack's thread view exposes unread followed threads, not a complete
+      # subscriptions cursor. Union the first page, and verify participation.
+      def subscribed_changes(existing, local)
+        response = subscribed_view
+        return [] unless response
+
+        known = existing.map { |change| [change.conversation.channel_id, change.conversation.thread_ts] }
+        known.concat(local.flat_map do |(_name, channel), entries|
+          entries.map { |_workspace, hit| [channel, hit.thread_ts || hit.ts] }
+        end)
+        response.fetch('threads', []).filter_map do |item|
+          root = item['root_msg'] || {}
+          channel = root['channel']
+          timestamp = root['thread_ts'] || root['ts']
+          next unless channel && timestamp && !known.include?([channel, timestamp])
+
+          seed = subscription_seed(channel, timestamp, root)
+          next unless seed
+
+          thread_change(seed, timestamp, require_participation: true)
+        end
+      end
+
+      def subscribed_view
+        @runner.threads_api(@workspace.name).get_view(limit: 100)
+      rescue ApiError => e
+        # Only unsupported/unauthorized-to-use subscription views are optional.
+        # Network, rate-limit and other failures must not look like a clean check-in.
+        raise unless OPTIONAL_SUBSCRIPTION_ERRORS.include?(e.code)
+
+        nil
+      end
+
+      def subscription_seed(channel, timestamp, root)
+        info = @api.info(channel: channel).fetch('channel', {})
+        type = if info['is_im']
+                 'im'
+               elsif info['is_mpim']
+                 'mpim'
+               else
+                 'channel'
+               end
+        name = type == 'im' ? info['user'] : info['name']
+        return unless name
+
+        Models::SearchResult.new(ts: timestamp, user_id: @self_id, username: nil, text: root['text'].to_s,
+                                 channel_id: channel, channel_name: name, channel_type: type,
+                                 thread_ts: timestamp, reply_count: 0, permalink: nil, files: [])
+      end
+
+      def dm_changes(hits, claimed)
+        seed = hits.first
+        probe = @api.history(channel: seed.channel_id, oldest: @since_ts, limit: 1)
+        recent = if probe['has_more']
+                   page_through(:history, channel: seed.channel_id, oldest: @since_ts)
+                 else
+                   probe.fetch('messages', [])
+                 end
+        fresh = after_cutoff(recent).reject { |row| claimed[row['ts']] }
+        return [] if fresh.empty?
+
+        earlier = if @context.zero?
+                    []
+                  else
+                    @api.history(channel: seed.channel_id, latest: @since_ts,
+                                 inclusive: true, limit: @context).fetch('messages', [])
+                  end
+        context = previous_messages(earlier)
+        [change(seed, seed.channel_type, nil, fresh, context)]
+      end
+
+      def channel_changes(hits, claimed)
+        recent = hits.select { |hit| top_level?(hit) && newer?(hit.ts) }
+        return [] if recent.empty?
+
+        windows = SentConversations.new(runner: @runner, start_date: @since.to_date, end_date: Date.today,
+                                        before: @before, after_minutes: @after_minutes, max: 0).collect(
+                                          recent.map { |hit| [@workspace, hit] }
+                                        )
+        own_timestamps = recent.to_h { |hit| [hit.ts, true] }
+        windows.filter_map do |window|
+          next unless window.type == 'channel'
+
+          fresh = window.messages.select { |msg| own_timestamps[msg.ts] && !claimed[msg.ts] }
+          next if fresh.empty?
+
+          context = previous_messages(window.messages)
+          change(hits.first, 'channel', nil, fresh, context)
+        end
+      end
+
+      def top_level?(hit)
+        hit.thread_ts.nil? || hit.thread_ts == hit.ts
+      end
+
+      def previous_messages(raw, parent_ts: nil)
+        older = raw.select { |row| row_timestamp(row) && !newer?(row_timestamp(row)) }
+        older = older.last(@context) unless @context.zero?
+        older = [] if @context.zero?
+        return older unless parent_ts && @context.positive?
+
+        parent = raw.find { |row| row_timestamp(row) == parent_ts }
+        parent && !newer?(parent_ts) ? ([parent] + older.reject { |row| row == parent }.last(@context - 1)) : older
+      end
+
+      # Counts and last speaker are calculated before --max hides any output.
+      def change(seed, type, root, fresh, context)
+        messages = normalize(context + fresh, seed.channel_id)
+        new_ts = fresh.map { |row| row_timestamp(row) }.uniq
+        new_messages = messages.select { |message| new_ts.include?(message.ts) }
+        return if new_messages.empty?
+
+        kept = @max.zero? ? messages : messages.last(@max)
+        conversation = Conversation.new(
+          workspace: @workspace, channel_id: seed.channel_id, channel_name: seed.channel_name,
+          channel_type: seed.channel_type, type: type, thread_ts: root, first_sent_ts: seed.ts,
+          messages: kept, last_speaker_is_me: new_messages.last.user_id == @self_id,
+          dropped_messages: messages.size - kept.size, self_user_id: @self_id,
+          self_username: seed.username
+        )
+        others = new_messages.count { |message| message.user_id != @self_id }
+        Change.new(conversation: conversation, new_timestamps: new_ts,
+                   new_count: new_messages.size, new_from_others: others)
+      end
+
+      def normalize(raw, channel_id)
+        raw.map { |row| row.is_a?(Models::Message) ? row : Models::Message.from_api(row, channel_id: channel_id) }
+           .uniq(&:ts).sort_by { |message| BigDecimal(message.ts) }
+      end
+
+      def after_cutoff(raw)
+        raw.select { |row| row['ts'] && newer?(row['ts']) && (row['user'] || row['bot_id'] || row['username']) }
+      end
+
+      def row_timestamp(row)
+        row.is_a?(Models::Message) ? row.ts : row['ts']
+      end
+
+      def newer?(timestamp)
+        BigDecimal(timestamp) > BigDecimal(@since_ts)
+      end
+
+      def page_through(endpoint, **params)
+        messages = []
+        cursor = nil
+        loop do
+          response = @api.public_send(endpoint, **params, limit: 200, cursor: cursor)
+          messages.concat(response.fetch('messages', []))
+          break unless response['has_more']
+
+          cursor = next_cursor!(response, cursor, endpoint)
+        end
+        messages
+      end
+
+      def next_cursor!(response, previous, endpoint)
+        cursor = response.dig('response_metadata', 'next_cursor').to_s
+        raise ApiError, "conversations.#{endpoint} has_more without a new cursor" if cursor.empty? || cursor == previous
+
+        cursor
+      end
+    end
+    # rubocop:enable Metrics/ClassLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/MethodLength
+  end
+end

data/lib/slk/services/sent_channel_label.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Slk
+  module Services
+    # Resolves sent-conversation destinations while retaining raw channel IDs
+    # and names in JSON. Group DMs need member lookup: their Slack name is an
+    # opaque mpdm-* slug, not a user ID that MentionReplacer can resolve.
+    class SentChannelLabel
+      USER_ID_PATTERN = /\A[UW][A-Z0-9]+\z/
+
+      def initialize(runner:)
+        @runner = runner
+        @labels = {}
+      end
+
+      # rubocop:disable Metrics/ParameterLists
+      def label(workspace:, type:, name:, channel_id:, self_user_id: nil, self_username: nil)
+        key = [workspace.name, channel_id, self_user_id]
+        @labels[key] ||= if type == 'mpim'
+                           group_label(workspace, channel_id, name, self_user_id, self_username)
+                         else
+                           @runner.search_formatter.channel_label_for(type, name, workspace)
+                         end
+      end
+
+      # rubocop:enable Metrics/ParameterLists
+
+      private
+
+      def group_label(workspace, channel_id, name, self_user_id, self_username)
+        names = group_member_names(workspace, channel_id, self_user_id)
+        return "@#{names.join(', ')}" if names.any?
+
+        fallback_group_label(name, self_username)
+      rescue ApiError
+        fallback_group_label(name, self_username)
+      end
+
+      def group_member_names(workspace, channel_id, self_user_id)
+        members = @runner.conversations_api(workspace.name).info(channel: channel_id).dig('channel', 'members') || []
+        names = members.reject { |id| id == self_user_id }.map { |id| resolve_name(workspace, id) }
+        names.any? { |value| value.match?(USER_ID_PATTERN) } ? [] : names
+      end
+
+      def resolve_name(workspace, user_id)
+        Services::UserLookup.new(cache_store: @runner.cache_store, workspace: workspace,
+                                 api_client: @runner.api_client).resolve_name_or_bot(user_id) || user_id
+      end
+
+      def fallback_group_label(name, self_username)
+        handles = name.to_s.sub(/\Ampdm-/, '').sub(/-\d+\z/, '').split('--')
+        people = handles.reject { |handle| normalized_handle(handle) == normalized_handle(self_username) }
+        people = handles if people.empty?
+        "@#{people.map { |handle| pretty_handle(handle) }.join(', ')}"
+      end
+
+      def normalized_handle(handle)
+        handle.to_s.downcase.gsub(/[^a-z0-9]/, '')
+      end
+
+      def pretty_handle(handle)
+        handle.tr('._-', ' ').split.map(&:capitalize).join(' ')
+      end
+    end
+  end
+end

data/lib/slk/services/sent_conversations.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require 'bigdecimal'
+
+module Slk
+  module Services
+    # Expands indexed from:me hits into bounded channel windows, full DM
+    # histories and full threads. Search is the seed, not the context source.
+    # rubocop:disable Metrics/ClassLength
+    class SentConversations
+      Conversation = Data.define(:workspace, :channel_id, :channel_name, :channel_type, :type, :thread_ts,
+                                 :first_sent_ts, :messages, :last_speaker_is_me, :dropped_messages,
+                                 :self_user_id, :self_username)
+      DEFAULT_BEFORE = 5
+      DEFAULT_AFTER_MINUTES = 30
+      DEFAULT_MAX = 200
+
+      # A date span plus three independent window/output limits.
+      # rubocop:disable Metrics/ParameterLists
+      def initialize(runner:, start_date:, end_date:, before: DEFAULT_BEFORE,
+                     after_minutes: DEFAULT_AFTER_MINUTES, max: DEFAULT_MAX)
+        @runner = runner
+        @start_date = start_date
+        @end_date = end_date
+        @before = before
+        @after_seconds = after_minutes * 60
+        @max = max
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      def collect(entries)
+        @self_ids = entries.to_h { |workspace, result| [workspace.name, self_id(workspace, result)] }
+        groups = entries.group_by { |workspace, result| [workspace.name, result.channel_id] }
+        conversations = groups.flat_map { |_key, group| collect_channel(group) }
+        # A thread parent can also appear in a channel window / DM history.
+        # Thread owns the message so the same (channel, ts) is never repeated.
+        ordered_conversations(deduplicate(conversations))
+      end
+
+      private
+
+      def ordered_conversations(conversations)
+        conversations.sort_by do |conversation|
+          # Keep Slack's fractional timestamp precise; identity breaks ties regardless of input order or platform.
+          [BigDecimal(conversation.first_sent_ts), conversation.workspace.name.to_s,
+           conversation.channel_id.to_s, conversation.thread_ts.to_s]
+        end
+      end
+
+      # Partitioning a channel needs both the reply roots and unthreaded hits.
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      def collect_channel(group)
+        workspace, seed = group.first
+        hits = group.map(&:last)
+        @self_id = @self_ids[workspace.name]
+        @api = @runner.conversations_api(workspace.name)
+        threaded = hits.select { |hit| hit.thread_ts && hit.thread_ts != hit.ts }.group_by(&:thread_ts)
+        ordinary = hits.reject { |hit| threaded.key?(hit.thread_ts) || threaded.key?(hit.ts) }
+        threads = threaded.map do |root, results|
+          parent_hit = hits.find { |hit| hit.ts == root }
+          thread_hits = parent_hit ? [parent_hit, *results] : results
+          thread_conversation(workspace, seed, root, thread_hits)
+        end
+        spans = if seed.dm?
+                  ordinary.empty? ? [] : [dm_conversation(workspace, seed, ordinary)]
+                else
+                  channel_conversations(workspace, seed, ordinary)
+                end
+        threads + spans
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+
+      def self_id(workspace, result)
+        return result.user_id if result.user_id.to_s.match?(/\A[UW][A-Z0-9]+\z/i)
+
+        cached = @runner.cache_store.get_meta(workspace.name, 'self_user_id')
+        return cached if cached
+
+        id = @runner.client_api(workspace.name).auth_test['user_id']
+        raise ApiError, "Cannot identify sender in #{workspace.name}" unless id
+
+        @runner.cache_store.set_meta(workspace.name, 'self_user_id', id)
+        id
+      end
+
+      def thread_conversation(workspace, seed, root, hits)
+        raw = thread_messages(seed.channel_id, root)
+        build(workspace, seed, 'thread', root, hits, raw)
+      end
+
+      def dm_conversation(workspace, seed, hits)
+        start_at = @start_date.to_time.to_i
+        # Slack's latest is exclusive; +1 includes messages in this second.
+        end_at = [(@end_date + 1).to_time.to_i, Time.now.to_i + 1].min
+        raw = page_through(:history, channel: seed.channel_id, oldest: start_at.to_s, latest: end_at.to_s)
+        build(workspace, seed, seed.channel_type, nil, hits, raw, expand_threads: true)
+      end
+
+      def channel_conversations(workspace, seed, hits)
+        merge_windows(hits).map { |window| channel_window(workspace, seed, window) }
+      end
+
+      def channel_window(workspace, seed, window)
+        preceding = preceding_messages(seed.channel_id, window.first.ts)
+        following = following_messages(seed.channel_id, window)
+        build(workspace, seed, 'channel', nil, window, preceding + following, expand_threads: true)
+      end
+
+      def preceding_messages(channel_id, timestamp)
+        return [] if @before.zero?
+
+        @api.history(channel: channel_id, latest: timestamp, limit: @before).fetch('messages', [])
+      end
+
+      def following_messages(channel_id, window)
+        return [] if @after_seconds.zero?
+
+        end_at = (BigDecimal(window.last.ts) + @after_seconds).to_s('F')
+        page_through(:history, channel: channel_id, oldest: window.first.ts, latest: end_at, inclusive: true)
+      end
+
+      def merge_windows(hits)
+        hits.sort_by { |hit| hit.ts.to_f }.each_with_object([]) do |hit, windows|
+          if windows.any? && hit.ts.to_f <= windows.last.last.ts.to_f + @after_seconds
+            windows.last << hit
+          else
+            windows << [hit]
+          end
+        end
+      end
+
+      def thread_messages(channel_id, root)
+        page_through(:replies, channel: channel_id, timestamp: root)
+      end
+
+      # Cursor follow-up is necessary even when the first page is full.
+      # rubocop:disable Metrics/MethodLength
+      def page_through(endpoint, **params)
+        messages = []
+        cursor = nil
+        loop do
+          response = @api.public_send(endpoint, **params, limit: 200, cursor: cursor)
+          messages.concat(response.fetch('messages', []))
+          break unless response['has_more']
+
+          next_cursor = response.dig('response_metadata', 'next_cursor').to_s
+          if next_cursor.empty? || next_cursor == cursor
+            raise ApiError, "conversations.#{endpoint} has_more without a new cursor"
+          end
+
+          cursor = next_cursor
+        end
+        messages
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      # Keep the search hits as a fallback at Slack's exclusive history bounds.
+      # rubocop:disable Metrics/ParameterLists
+      def build(workspace, seed, type, root, hits, raw, expand_threads: false)
+        # Search's own hits ensure an indexed sent message cannot disappear just
+        # because history omits thread replies or returns a window boundary.
+        raw += hits.map { |hit| search_message(hit) }
+        raw = expand_own_threads(raw, seed, hits) if expand_threads
+        messages = normalize(raw, seed.channel_id)
+        last_is_me = messages.last&.user_id == @self_id
+        Conversation.new(workspace: workspace, channel_id: seed.channel_id, channel_name: seed.channel_name,
+                         channel_type: seed.channel_type, type: type, thread_ts: root, first_sent_ts: hits.first.ts,
+                         messages: messages, last_speaker_is_me: last_is_me, dropped_messages: 0,
+                         self_user_id: @self_id, self_username: hits.first.username)
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      def search_message(hit)
+        { 'ts' => hit.ts, 'user' => @self_id, 'username' => hit.username, 'text' => hit.text,
+          'thread_ts' => hit.thread_ts, 'reply_count' => hit.reply_count }
+      end
+
+      def expand_own_threads(raw, seed, hits)
+        own_roots(raw, seed, hits).each { |root| raw.concat(thread_messages(seed.channel_id, root)) }
+        raw
+      end
+
+      def own_roots(raw, seed, hits)
+        # Five preceding channel messages may include an old post of ours;
+        # don't expand its unrelated thread into today's conversation.
+        earliest = seed.dm? ? @start_date.to_time.to_i : hits.first.ts.to_f
+        raw.filter_map { |message| message['ts'] if own_thread_root?(message, earliest) }.uniq
+      end
+
+      def own_thread_root?(message, earliest)
+        message['user'] == @self_id && message['reply_count'].to_i.positive? &&
+          message['ts'].to_f >= earliest
+      end
+
+      def normalize(raw, channel_id)
+        raw.select { |message| readable?(message) }
+           .uniq { |message| message['ts'] }
+           .sort_by { |message| message['ts'].to_f }
+           .map { |message| Models::Message.from_api(message, channel_id: channel_id) }
+      end
+
+      def readable?(message)
+        message['ts'] && (message['user'] || message['bot_id'] || message['username'])
+      end
+
+      def deduplicate(conversations)
+        seen = {}
+        conversations.filter_map { |conversation| unique_conversation(conversation, seen) }
+      end
+
+      # Global dedupe happens before --max so a duplicate cannot consume a slot.
+      # rubocop:disable Metrics/AbcSize
+      def unique_conversation(conversation, seen)
+        key = [conversation.workspace.name, conversation.channel_id]
+        unique = conversation.messages.reject { |message| seen[[*key, message.ts]] }
+        return if unique.empty?
+
+        unique.each { |message| seen[[*key, message.ts]] = true }
+        kept = @max.zero? ? unique : unique.last(@max)
+        conversation.with(messages: kept, dropped_messages: unique.size - kept.size,
+                          last_speaker_is_me: unique.last.user_id == @self_ids[conversation.workspace.name])
+      end
+      # rubocop:enable Metrics/AbcSize
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/slk/services/start_date_field.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Slk
+  module Services
+    # Which custom profile field holds a start date, if any.
+    #
+    # Workspaces name and number these fields themselves, so the ID has to be
+    # discovered from the team schema rather than hardcoded — and the schema
+    # barely changes, so the answer is cached for a week.
+    class StartDateField
+      CACHE_KEY = 'start_date_field_v1'
+      TTL = 604_800 # 7 days
+      LABEL = /\Astart date\z/i
+
+      def initialize(team_api:, workspace_name:, cache_store: nil, on_debug: nil)
+        @team_api = team_api
+        @workspace_name = workspace_name
+        @cache = cache_store
+        @on_debug = on_debug
+      end
+
+      # @return [String, nil] the Xf… field ID, or nil if the workspace has none
+      def id
+        return @id if defined?(@id)
+
+        cached = MetaCache.read(@cache, @workspace_name, CACHE_KEY, ttl: TTL)
+        @id = cached.is_a?(Hash) ? cached['id'] : discover
+      end
+
+      def missing_message
+        'This workspace has no "Start Date" profile field, so tenure cannot be worked out. ' \
+          'Run `slk debug schema` (an undocumented command) to see the fields it does have.'
+      end
+
+      private
+
+      # A date-typed field wins over a text one with the same label: someone
+      # typing "started summer 2019" into a text box is not a date.
+      def discover
+        id = usable_id(best_match(@team_api.profile_schema.dig('profile', 'fields')))
+        @on_debug&.call("start date field: #{id || 'not found in team schema'}")
+        remember(id)
+        id
+      end
+
+      def usable_id(match)
+        id = match && match['id']
+        id.is_a?(String) && !id.empty? ? id : nil
+      end
+
+      # Losing this costs one extra team.profile.get next run, not minutes of
+      # rate-limited lookups, so it is noted rather than warned about.
+      def remember(id)
+        failure = MetaCache.write(@cache, @workspace_name, CACHE_KEY, { 'id' => id })
+        @on_debug&.call("start date field cache not written: #{failure.message}") if failure
+      end
+
+      # A workspace that answers with something other than a list of field
+      # hashes has no start date field as far as we are concerned — better a
+      # clear "this workspace cannot do tenure" than an unexpected error.
+      def best_match(fields)
+        labelled = Array(fields).grep(Hash).select { |f| LABEL.match?(f['label'].to_s.strip) }
+        labelled.find { |f| f['type'] == 'date' } || labelled.first
+      end
+    end
+  end
+end