openlanes 3.0.0 → 3.1.0

data/lib/openlanes/plans/dependencies.rb

@@ -0,0 +1,304 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Plans
+    # Who waits for whom, read from every plan's `depends_on:` and nothing
+    # else. Only the forward edge is written down; `blocks` is derived here
+    # every time and never stored, so dropping a dependency cannot leave a
+    # stale reverse entry behind in the plan it used to name (N6).
+    #
+    # Every answer is an array of canonical `NNN.MM` strings, sorted. Asking
+    # about a plan the tree does not hold answers empty rather than raising.
+    #
+    # Plans joined by an unfinished edge, in either direction, form a group,
+    # and a group works on one plan at a time (#95): the first in topological
+    # order that may start, so two plans that will meet in a common dependent
+    # are never built against each other's moving code. Separate groups run
+    # side by side. An edge to a finished plan joins nothing, so the
+    # dependents of a shipped plan part ways.
+    class Dependencies
+      # The states in which a dependency is done. Everything else, blocked and
+      # deferred included, keeps the dependent waiting.
+      DONE = %i[approved deployed].freeze
+
+      # The states before the build. Work in them is documents only, so a plan
+      # here gives up its group's turn to one whose code is already under way.
+      BEFORE_BUILD = %i[retroactive new researched ready_for_planning planned].freeze
+
+      # @param tree [OpenLanes::Plans::Tree]
+      # @param status_of [#call, nil] the state to judge a plan by, when it is
+      #   not the folder's name. A dry run renames nothing, so without this a
+      #   prerequisite whose contents already say ✅ would still hold its
+      #   dependents back, while a real run would have reconciled it and let
+      #   them start.
+      def initialize(tree, status_of: nil)
+        @tree = tree
+        @status_of = status_of || :status.to_proc
+      end
+
+      # @param ordinal [OpenLanes::Plans::Ordinal, String]
+      # @return [Array<String>, nil] the declared list, nil when the key is absent
+      def depends_on(ordinal) = declared[key(ordinal)]
+
+      # @param ordinal [OpenLanes::Plans::Ordinal, String]
+      # @return [Array<String>] every plan whose `depends_on` names this one
+      def blocks_of(ordinal) = reverse.fetch(key(ordinal), [])
+
+      # @param ordinal [OpenLanes::Plans::Ordinal, String]
+      # @return [Array<String>] declared entries that are not done, unknown ones included
+      def waiting_on(ordinal) = edges(ordinal).reject { done?(it) }
+
+      # @param ordinal [OpenLanes::Plans::Ordinal, String]
+      # @return [Array<String>] declared entries with no folder in the tree
+      def unknown(ordinal) = edges(ordinal).reject { states.key?(it) }
+
+      # @param ordinal [OpenLanes::Plans::Ordinal, String]
+      # @return [Array<String>] declared entries naming a done plan, which the gate ignores
+      def closed(ordinal) = edges(ordinal).select { done?(it) }
+
+      # @param ordinal [OpenLanes::Plans::Ordinal, String]
+      # @return [Array<String>, nil] a shortest cycle through this plan,
+      #   starting and ending with it, or nil when it is on none
+      def cycle_of(ordinal)
+        wanted = key(ordinal)
+        return nil unless looped?(wanted)
+
+        (@rings ||= {})[wanted] ||= ring_from(wanted)
+      end
+
+      # One shortest cycle per tangle of plans that wait on each other, each
+      # starting and ending at the tangle's lowest ordinal. A tangle can hold
+      # more cycles than this; {#cycle_of} names one through any plan in it.
+      #
+      # @return [Array<Array<String>>]
+      def cycles = @cycles ||= components.select { looped?(it.first) }.map { cycle_of(it.first) }.sort
+
+      # Unfinished plans joined by an unfinished edge, in either direction.
+      #
+      # @return [Array<Array<String>>] each group sorted, groups by first ordinal
+      def groups
+        @groups ||= begin
+          # Union-find, walked in a loop rather than recursively, so a long
+          # chain of plans cannot raise SystemStackError inside a tick.
+          root = unfinished.to_h { [it, it] }
+          find = lambda do |x|
+            x = root[x] = root[root[x]] until root[x] == x
+            x
+          end
+          unfinished.each do |from|
+            open_edges.fetch(from).each { |to| root[find.call(from)] = find.call(to) if root.key?(to) }
+          end
+          unfinished.group_by { find.call(it) }.values.map(&:sort).sort
+        end
+      end
+
+      # Each group in topological order, prerequisites first, ties by
+      # ordinal. Plans on a cycle cannot be ordered and come last.
+      #
+      # @return [Array<Array<String>>] parallel to {#groups}
+      def order = @order ||= groups.map { sorted(it) }
+
+      # The plan whose turn it is in this plan's group, or nil when no plan
+      # in it may start: the first in {#order} that may, preferring one whose
+      # build is already under way, so work already done is never stranded.
+      #
+      # @param ordinal [OpenLanes::Plans::Ordinal, String]
+      # @return [String, nil]
+      def head(ordinal)
+        wanted = key(ordinal)
+        line = order.find { it.include?(wanted) } or return nil
+        (@heads ||= {}).fetch(line.first) do
+          ready = line.select { startable?(it) }
+          @heads[line.first] = ready.find { !BEFORE_BUILD.include?(states[it]) } || ready.first
+        end
+      end
+
+      # Why the engine must not start this plan, or nil when it may. A cycle
+      # outranks a plain wait, since waiting on a cycle never ends. An entry
+      # naming no plan is said apart from a real wait: a typo such as
+      # "099.00" holds the plan forever, and "waiting on 099.00" in the held
+      # report read like a wait that would end on its own. A plan free of
+      # all three still waits while another plan holds its group's turn.
+      #
+      # @param ordinal [OpenLanes::Plans::Ordinal, String]
+      # @return [String, nil] e.g. "waiting on 034.00", "unknown plan 099.00",
+      #   "cycle: 034.00 → 050.00 → 034.00" or "queued behind 034.00"
+      def reason(ordinal)
+        own = own_reason(ordinal) and return own
+
+        first = head(ordinal)
+        "queued behind #{first}" if first && first != key(ordinal)
+      end
+
+      private
+
+      # {#reason} without the group's turn: what this plan's own edges say.
+      #
+      # @param ordinal [OpenLanes::Plans::Ordinal, String]
+      # @return [String, nil]
+      def own_reason(ordinal)
+        cycle = cycle_of(ordinal)
+        return "cycle: #{cycle.join(" → ")}" if cycle
+
+        missing = unknown(ordinal)
+        open = waiting_on(ordinal) - missing
+        parts = []
+        parts << "unknown plan #{missing.join(", ")}" unless missing.empty?
+        parts << "waiting on #{open.join(", ")}" unless open.empty?
+        parts.join("; ") unless parts.empty?
+      end
+
+      # @return [Boolean] whether this plan could take its group's turn:
+      #   neither parked nor done, and free of its own reasons to wait
+      def startable?(ordinal) = !StateMachine::SETTLED.include?(states[ordinal]) && own_reason(ordinal).nil?
+
+      # @return [Array<String>] plans in the tree that are not done
+      def unfinished = @unfinished ||= declared.keys.reject { done?(it) }.sort
+
+      # Kahn's algorithm over the group's open edges, taking the lowest
+      # ordinal whenever several plans are free. The free list stays sorted
+      # by binary insertion, so a group of thousands sorts in a blink.
+      #
+      # @param group [Array<String>]
+      # @return [Array<String>]
+      def sorted(group)
+        members = group.to_set
+        pending = group.to_h { |plan| [plan, open_edges.fetch(plan).count { members.include?(it) }] }
+        free = pending.select { |_, n| n.zero? }.keys.sort
+        out = []
+        until free.empty?
+          plan = free.shift
+          out << plan
+          pending.delete(plan)
+          blocks_of(plan).each do |waiter|
+            next unless pending.key?(waiter) && (pending[waiter] -= 1).zero?
+
+            free.insert(free.bsearch_index { it >= waiter } || free.size, waiter)
+          end
+        end
+        out + pending.keys.sort
+      end
+
+      # @return [String]
+      def key(ordinal) = (ordinal.is_a?(Ordinal) ? ordinal : Ordinal.parse(ordinal)).to_s
+
+      # @return [Array<String>]
+      def edges(ordinal) = depends_on(ordinal) || []
+
+      # @return [Boolean]
+      def done?(ordinal) = DONE.include?(states[ordinal])
+
+      # @return [Hash{String => Symbol}] ordinal => status key
+      def states = @states ||= @tree.subjects.to_h { [it.feature.ordinal.to_s, @status_of.call(it).key] }
+
+      # @return [Hash{String => Array<String>, nil}]
+      def declared
+        @declared ||= @tree.subjects.to_h { [it.feature.ordinal.to_s, Spec.for(it).depends_on] }
+      end
+
+      # @return [Hash{String => Array<String>}]
+      def reverse
+        @reverse ||= declared.each_with_object(Hash.new { |h, k| h[k] = [] }) do |(from, tos), out|
+          Array(tos).each { out[it] << from }
+        end.transform_values(&:sort)
+      end
+
+      # The edges that can still hold anything up: entries not yet done that
+      # name a plan in the tree. A dependency on a ✅ plan is already met, so
+      # it closes no cycle; two plans that once named each other stop being
+      # deadlocked the moment one of them ships.
+      #
+      # @return [Hash{String => Array<String>}]
+      def open_edges = @open_edges ||= declared.keys.to_h { [it, waiting_on(it).select { declared.key?(it) }] }
+
+      # @return [Boolean] whether this plan sits on a cycle of open edges
+      def looped?(ordinal)
+        group = group_of[ordinal] or return false
+        group.size > 1 || open_edges.fetch(ordinal).include?(ordinal)
+      end
+
+      # @return [Hash{String => Array<String>}] ordinal => its strongly connected component
+      def group_of = @group_of ||= components.each_with_object({}) { |g, out| g.each { out[it] = g } }
+
+      # Tarjan's strongly connected components over {#open_edges}, so each
+      # plan is visited once. Enumerating every path instead revisited shared
+      # subgraphs on each one: 28 plans each waiting on the two before took
+      # 2.6 seconds and two million visits, and the dispatcher asks on every
+      # tick. The walk keeps its own stack of frames rather than recursing,
+      # so a chain of a few thousand plans cannot raise SystemStackError
+      # inside a dispatcher tick.
+      #
+      # @return [Array<Array<String>>] each component sorted
+      def components
+        @components ||= begin
+          index = {}
+          low = {}
+          stack = []
+          on_stack = {}
+          out = []
+          open_edges.keys.sort.each do |root|
+            next if index.key?(root)
+
+            frames = [[root, 0]]
+            index[root] = low[root] = index.size
+            stack << root
+            on_stack[root] = true
+            until frames.empty?
+              v, i = frames.last
+              w = open_edges.fetch(v)[i]
+              if w
+                frames.last[1] += 1
+                if !index.key?(w)
+                  index[w] = low[w] = index.size
+                  stack << w
+                  on_stack[w] = true
+                  frames << [w, 0]
+                elsif on_stack[w]
+                  low[v] = [low[v], index[w]].min
+                end
+                next
+              end
+
+              frames.pop
+              parent = frames.last&.first
+              low[parent] = [low[parent], low[v]].min if parent
+              next unless low[v] == index[v]
+
+              group = []
+              group << stack.pop.tap { on_stack.delete(it) } until group.last == v
+              out << group.sort
+            end
+          end
+          out
+        end
+      end
+
+      # Breadth-first from +start+ back to itself inside its component, so
+      # the cycle named is a shortest one and the walk is linear.
+      #
+      # @param start [String]
+      # @return [Array<String>]
+      def ring_from(start)
+        group = group_of.fetch(start)
+        parent = { start => nil }
+        queue = [start]
+        until queue.empty?
+          node = queue.shift
+          open_edges.fetch(node).sort.each do |nxt|
+            next unless group.include?(nxt)
+
+            if nxt == start
+              path = [node]
+              path.unshift(parent[path.first]) while parent[path.first]
+              return path + [start]
+            end
+            next if parent.key?(nxt)
+
+            parent[nxt] = node
+            queue << nxt
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openlanes/plans/feature.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "date"
+
 module OpenLanes
   module Plans
     # Lowercase in the middle of a title, capitalised at the front.
@@ -45,22 +47,36 @@ module OpenLanes
       }.join(" ")
     end
 
-    # The one place a plan folder's name is spelled out: `NNN.MM-<emoji> → <slug>`.
+    # The heavy rule between the parts of a folder name. No space anywhere, so
+    # a name needs no quoting in a shell, and nothing an emoji can swallow.
+    RULE = "━━"
+
+    # What points from the state to the slug.
+    POINTER = "❯"
+
+    # The one place a plan folder's name is spelled out (decision N1):
+    # `NNN.MM━━<emoji>━━❯<slug>`, or `NNN.MM━━<emoji>━━❯[YYYY-MM-DD]━━<slug>`
+    # once the plan has been moved into an inactive subfolder (N3).
     #
-    # The spaced arrow after the emoji is deliberate: an emoji renders two cells
-    # wide and visually swallows a bare dash beside it, so `🔎-refactor` reads
-    # as if the emoji and the slug were touching. Everything that mints or
-    # renames a folder goes through here; {Feature.parse} accepts the older
-    # `--` and single-dash spellings too, and `resync dirs` migrates them on
-    # contact.
+    # The earlier `NNN.MM-<emoji> → <slug>` put a space in every name, and the
+    # `--` before it let a two-cell emoji swallow the dash beside it.
+    # Everything that mints or renames a folder goes through here; {Feature.parse}
+    # still reads every older spelling, and `resync dirs` migrates them.
     #
     # @param ordinal [OpenLanes::Plans::Ordinal, String]
     # @param status [OpenLanes::Plans::Status]
     # @param slug [String]
+    # @param archived_on [Date, nil] the date the plan was moved aside
     # @return [String]
-    def self.plan_dirname(ordinal, status, slug) = "#{ordinal}-#{status.emoji} → #{slug}"
+    def self.plan_dirname(ordinal, status, slug, archived_on: nil)
+      date = archived_on && "[#{archived_on.strftime("%F")}]#{RULE}"
+      "#{ordinal}#{RULE}#{status.emoji}#{RULE}#{POINTER}#{date}#{slug}"
+    end
+
+    # The current spelling, with or without the archive date.
+    CURRENT_FORM = /\A[\d.]+#{RULE}(?<emoji>[^━]+)#{RULE}#{POINTER}(?:\[(?<date>\d{4}-\d{2}-\d{2})\]#{RULE})?(?<slug>.+)\z/
 
-    # One `NNN.MM-<emoji> → <slug>` folder, decoded.
+    # One plan folder, decoded.
     #
     # @!attribute [r] ordinal
     #   @return [OpenLanes::Plans::Ordinal]
@@ -72,9 +88,14 @@ module OpenLanes
     #   @return [String] exactly as it is on disk
     # @!attribute [r] path
     #   @return [String] absolute
-    Feature = Data.define(:ordinal, :status, :slug, :dirname, :path) do
+    # @!attribute [r] archived_on
+    #   @return [Date, nil] the date in the name of a plan moved aside, else nil
+    Feature = Data.define(:ordinal, :status, :slug, :dirname, :path, :archived_on) do
       include Comparable
 
+      # @param archived_on [Date, nil] optional, so callers that predate it still build one
+      def initialize(archived_on: nil, **) = super
+
       # Decode a folder name, or return nil when it is not a plan folder.
       #
       # @param path [String] absolute path to a candidate directory
@@ -83,29 +104,67 @@ module OpenLanes
         dirname = File.basename(path)
         ordinal = Ordinal.from_dirname(dirname) or return nil
 
+        current(dirname, ordinal, path) || legacy(dirname, ordinal, path)
+      end
+
+      # `NNN.MM━━<emoji>━━❯<slug>`, dated or not.
+      #
+      # An emoji nothing answers to reads as ⚪ New rather than falling through
+      # to {.legacy}, which cannot split this spelling and took the whole name
+      # for the slug; the next rename then wrote
+      # `001.00━━⭕━━❯001.00━━🛑━━❯slug`. A name already nested that way is
+      # read down to its innermost slug, so `resync dirs` can undo it.
+      #
+      # @return [OpenLanes::Plans::Feature, nil]
+      def self.current(dirname, ordinal, path)
+        m = CURRENT_FORM.match(dirname) or return nil
+        status = OpenLanes::Plans.status_for_emoji(m[:emoji]) || STATUS_BY_KEY.fetch(:new)
+        archived_on = m[:date] && Date.iso8601(m[:date], exception: false)
+
+        new(ordinal:, status:, slug: innermost(m[:slug], ordinal), dirname:, path:, archived_on:)
+      end
+
+      # @param slug [String]
+      # @param ordinal [OpenLanes::Plans::Ordinal]
+      # @return [String] +slug+ without any plan prefix of the same ordinal
+      def self.innermost(slug, ordinal)
+        return slug unless Ordinal.from_dirname(slug) == ordinal
+
+        parse(slug)&.slug || slug
+      end
+
+      # `NNN.MM-<emoji> → <slug>`, `NNN-<emoji>--<slug>` and `NNN-<emoji>-<slug>`.
+      #
+      # @return [OpenLanes::Plans::Feature]
+      def self.legacy(dirname, ordinal, path)
         rest = dirname.sub(/\A[\d.]+[-_]/, "")
         head, tail = rest.split(/\s*→\s*|[-_]/, 2)
 
         # A leading segment with no ASCII word character is the status emoji.
-        # The slug strips any further separators: the canonical spelling puts
-        # a spaced arrow after the emoji, and folders from before that rule put
-        # two dashes, or one.
+        # The slug strips any further separators: the arrow spelling put a
+        # spaced arrow after the emoji, and folders from before that put two
+        # dashes, or one.
         status = (OpenLanes::Plans.status_for_emoji(head) if tail && !head.to_s.empty? && !head.match?(/[A-Za-z0-9]/))
         slug = status ? tail.sub(/\A[-_\s]+/, "") : rest
 
         new(ordinal:, status: status || STATUS_BY_KEY.fetch(:new), slug:, dirname:, path:)
       end
+      private_class_method :current, :legacy, :innermost
 
       # @return [String] proper name, e.g. "Law as Data"
       def title = OpenLanes::Plans.titleize(slug)
 
       # The folder name this feature would carry in a given state — the slug
-      # never moves, and the number is always rendered canonically, so this is
-      # also what repairs a folder written `018-⚪️--foo` before the `NNN.MM` rule.
+      # and any archive date never move, and the number is always rendered
+      # canonically, so this is also what repairs a folder written
+      # `018-⚪️--foo` before the `NNN.MM` rule.
       #
       # @param status [OpenLanes::Plans::Status]
+      # @param archived_on [Date, nil] defaults to the date the name carries now
       # @return [String]
-      def dirname_as(status) = OpenLanes::Plans.plan_dirname(ordinal, status, slug)
+      def dirname_as(status, archived_on: self.archived_on)
+        OpenLanes::Plans.plan_dirname(ordinal, status, slug, archived_on:)
+      end
 
       # The number exactly as the folder writes it, which is not always the
       # canonical rendering: `018-⚪️--foo` yields "018" where {#ordinal} renders

data/lib/openlanes/plans/journal.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require "json"
+
+module OpenLanes
+  module Plans
+    # An agent's journal (M2): what it decided, did, left to do, asked and
+    # must not forget, kept from one round to the next.
+    #
+    # The agent writes no file and runs no command. It prints each entry as
+    # one line of JSON in its own output, which the harness reads anyway, and
+    # the dispatcher keeps it in `state.json` under `memory.<agent>`. One
+    # writer, under the lock {PlanState} already takes, is what lets a pair
+    # journal at once without either losing the other's line; an agent that
+    # wrote the file itself would be a second writer racing the first.
+    #
+    #     {"openlanes_memory": {"kind": "decision", "text": "Money is integer cents"}}
+    #     {"openlanes_memory": {"kind": "override", "text": "BigDecimal after all", "overrides": 3}}
+    #
+    # The single key {KEY} is what tells an entry from any other JSON an
+    # agent prints: a status object, a `package.json` it quotes, a `jq`
+    # result. Nothing else an agent has reason to print starts with that key.
+    #
+    # There is no timestamp. Entries are numbered in order across the
+    # agent's rounds on the plan, and a later one wins over an earlier one;
+    # an `override` names the number it overturns.
+    #
+    # Pure: text in, entries out. The dispatcher decides where they go.
+    module Journal
+      # The one key an entry line carries.
+      KEY = "openlanes_memory"
+
+      # What an entry may be. `question` is the agent stopping to ask; the
+      # harness adds the answer beside it once one arrives (M3).
+      KINDS = %w[todo done decision question override note].freeze
+
+      # Longest text kept, in characters. Every round's prompt carries the
+      # journal, so an entry is a line to remember, not a document; one that
+      # runs on is cut rather than refused, since what it says first is what
+      # it most needed to keep.
+      TEXT_LIMIT = 500
+
+      # A line that may be an entry: the key first, after an optional
+      # backtick, since agents quote JSON in Markdown as often as not.
+      CANDIDATE = /\A`*\{\s*"#{KEY}"\s*:/
+
+      # One entry, as the agent printed it or the harness recorded it.
+      #
+      # @!attribute [r] kind
+      #   @return [String] one of {KINDS}
+      # @!attribute [r] text
+      #   @return [String]
+      # @!attribute [r] overrides
+      #   @return [Integer, nil] the number of the entry an `override` overturns
+      # @!attribute [r] ref
+      #   @return [String, nil] `B<n>`, for a question the harness recorded
+      #     from `blocked.md`
+      # @!attribute [r] answer
+      #   @return [String, nil] a person's answer to that question
+      Entry = Data.define(:kind, :text, :overrides, :ref, :answer) do
+        def initialize(kind:, text:, overrides: nil, ref: nil, answer: nil) = super
+
+        # @param hash [Hash] as `state.json` keeps it
+        # @return [OpenLanes::Plans::Journal::Entry]
+        def self.from_h(hash)
+          new(kind: hash["kind"].to_s,
+            text: hash["text"].to_s,
+            overrides: hash["overrides"],
+            ref: hash["ref"],
+            answer: hash["answer"])
+        end
+
+        # @return [Hash] string keys, nils left out, as the schema wants
+        def to_json_h = to_h.transform_keys(&:to_s).compact
+      end
+
+      # A line that announced itself as an entry and was not one, kept so the
+      # dispatcher can say so: an agent whose journal is silently dropped
+      # believes it is remembering.
+      #
+      # @!attribute [r] line
+      #   @return [String]
+      # @!attribute [r] reason
+      #   @return [String]
+      Rejection = Data.define(:line, :reason)
+
+      # One round's worth of one agent's journal.
+      #
+      # @!attribute [r] number
+      #   @return [Integer] the agent's journal round on this plan, 1 up,
+      #     counted across runs and states. Not the dispatcher's round, which
+      #     restarts at 1 in every run and every state and would land a later
+      #     run's entries on an earlier run's.
+      # @!attribute [r] round
+      #   @return [Integer, nil] the dispatcher's round it was printed in
+      # @!attribute [r] state
+      #   @return [String, nil] the state the plan was in when it started
+      # @!attribute [r] entries
+      #   @return [Array<Entry>]
+      # @!attribute [r] first
+      #   @return [Integer] the number of its first entry in the whole journal
+      Round = Data.define(:number, :round, :state, :entries, :first)
+
+      module_function
+
+      # Every entry line in one piece of the agent's text, in order, each
+      # read into an {Entry} or a {Rejection}. Lines that do not start with
+      # {KEY} are none of this method's business and are skipped.
+      #
+      # @param text [String, nil] what the agent said
+      # @return [Array<Entry, Rejection>]
+      def scan(text)
+        text.to_s.each_line.filter_map do |raw|
+          line = raw.strip
+          read(line) if line.match?(CANDIDATE)
+        end
+      end
+
+      # @param line [String] one candidate line
+      # @return [Entry, Rejection]
+      def read(line)
+        json = line.delete_prefix("`" * line[/\A`*/].size).delete_suffix("`" * line[/`*\z/].size)
+        value = JSON.parse(json)[KEY]
+        problem = problem_with(value)
+        return Rejection.new(line:, reason: problem) if problem
+
+        Entry.new(kind: value["kind"], text: clip(value["text"]), overrides: value["overrides"])
+      rescue JSON::ParserError => e
+        Rejection.new(line:, reason: "not JSON: #{e.message.lines.first.to_s.strip}")
+      end
+
+      # Only the fields an agent may set are read; `ref` and `answer` are the
+      # harness's to write, and an agent claiming a person answered something
+      # is exactly the line that must not be trusted.
+      #
+      # @param value [Object]
+      # @return [String, nil] why it is not an entry
+      def problem_with(value)
+        return "#{KEY} is not an object" unless value.is_a?(Hash)
+        return "kind #{value["kind"].inspect} is not one of #{KINDS.join(", ")}" unless KINDS.include?(value["kind"])
+        return "text is missing" unless value["text"].is_a?(String) && !value["text"].strip.empty?
+
+        overrides = value["overrides"]
+        return nil if overrides.nil?
+        return "overrides must be an entry number" unless overrides.is_a?(Integer) && overrides.positive?
+
+        "only an override may name an entry it overrides" unless value["kind"] == "override"
+      end
+
+      # @param text [String]
+      # @return [String] stripped, and cut to {TEXT_LIMIT}
+      def clip(text)
+        text = text.to_s.strip
+        text.length > TEXT_LIMIT ? "#{text[0, TEXT_LIMIT - 1]}…" : text
+      end
+
+      # The line an agent prints, for the prompt's examples, so the prompt and
+      # the parser cannot describe two shapes.
+      #
+      # @param kind [String]
+      # @param text [String]
+      # @param overrides [Integer, nil]
+      # @return [String]
+      def line(kind, text, overrides: nil)
+        JSON.generate(KEY => { "kind" => kind, "text" => text, "overrides" => overrides }.compact)
+      end
+    end
+  end
+end