proctolog 0.1.0

data/app/models/proctolog/rounds.rb

@@ -0,0 +1,305 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # The rounds of a burst's review: every request the owner made, where it
+  # stands between them and the agent, and what the next pass hands over.
+  # All of it is read from what the desk keeps: the open notes and the code
+  # comments nobody resolved, the choices the pages write, the batch each
+  # handover carried and the answers that came back. So a pass can be taken
+  # with no page open, by the agent itself, halfway through a review. The
+  # pages' script shows the same rounds by the same rules, in
+  # review-rounds.js.
+  class Rounds
+    # A decision in its place in the burst, under the id the pages give it.
+    Placed = Data.define(:stop, :decision) do
+      def id = "#{pr}-#{decision.position}"
+
+      def pr = stop.number
+    end
+
+    # A choice or a draft a page kept, with the id its request goes by and
+    # the decision it was made on, while the burst still has it.
+    Choice = Data.define(:entry, :request_id, :at) do
+      def pr = entry.dig("decision", "pr")
+
+      def kind = entry["kind"]
+
+      def text = entry["text"].presence || entry.dig("decision", "lead")
+
+      # The decision as the choice was made on it, under the id it goes by
+      # now: a "missing:" one once the burst no longer has it.
+      def decision = entry["decision"].deep_symbolize_keys.merge(at ? {id: at.id, position: at.decision.position, key: at.decision.key} : {id: "missing:#{request_id}"})
+
+      # Left with every other non-blocking decision at once.
+      def in_bulk? = entry["batch"].present? && entry["grade"].present?
+
+      # The one answer given to several decisions it shares.
+      def together = entry["batch"].to_s.start_with?("together:") ? entry["batch"] : nil
+    end
+
+    # An answer to a request: the result, the response it came in, and the
+    # batch and request it answers, in the order the batches were written.
+    Answer = Data.define(:response, :result, :batch, :request, :order) do
+      # How the owner's reply names the answer it replies to.
+      def key = "#{response[:id]}:#{response[:createdAt]}"
+
+      def newness = [order, Rounds.moment(response[:createdAt])]
+    end
+
+    # A time as a page or an agent wrote it; one that cannot be read is
+    # taken for the oldest.
+    def self.moment(text)
+      Time.iso8601(text.to_s)
+    rescue ArgumentError
+      Time.at(0)
+    end
+
+    def initialize(burst, route:, focus: Focus.new(route, nil))
+      @burst, @route, @focus = burst, route, focus
+      @kept = burst.choices
+      @document = @kept.document || {}
+    end
+
+    # The owner's open notes and the code comments nobody resolved, across
+    # the whole burst, each as a request.
+    def requests
+      @requests ||= [*@route.flat_map { notes_of(it.number, pr: it.number) }, *notes_of("sitting", pr: nil),
+        *@route.flat_map { CodeReview.new(@burst, it.number).requests }]
+    end
+
+    # What the next pass asks of the agent, as a batch of its own, with what
+    # it should know beside. What an agent took and has not answered yet is
+    # held back, so that two never do the same work, unless taken `again`.
+    def worklist(batch_id: "preview", again: false, at: Time.current)
+      Handover::Worklist.new(batch_id:, created_at: at.utc.iso8601(3), heads:, items: work(again:),
+        with_agent: again ? [] : with_agent, awaiting_owner: ids_in(:owner, :question), closed: ids_in(:closed),
+        left_at_once:, answered_together:, unfinished_drafts:, unreviewed:)
+    end
+
+    # Each pull request of the burst at the head the desk read.
+    def heads = @heads ||= @route.to_h { [it.number, {head: it.head_oid, title: it.title, branch: it.pull_request.head, description: it.description.digest}] }
+
+    # For the next pass; out with an agent that has not answered; answered
+    # and the owner's to confirm, or to answer; closed; or kept from an
+    # earlier review for its context.
+    def state_of(item)
+      latest = latest(item)
+      reply = reply_to(item) if latest
+      if archived?(item) then :archived
+      elsif item[:kind] == "leave" then :closed
+      elsif reply&.dig(:replyTo) == latest&.key && reply&.dig(:resolution) == "confirmed" then :closed
+      elsif latest.nil? || reply&.dig(:replyTo) == latest.key then out?(item) ? :out : :agent
+      else (latest.result[:status] == "needs_owner") ? :question : :owner
+      end
+    end
+
+    # What an agent took and has not answered, with the handover it went in.
+    def with_agent
+      current.select { in_focus?(it[:pr]) && state_of(it) == :out }.map do |item|
+        batch = carrier(item)
+        {**item.slice(:id, :pr, :kind, :text), batchId: batch[:id], handedOverAt: batch[:createdAt]}
+      end
+    end
+
+    private
+
+    def work(again:)
+      current.select { in_focus?(it[:pr]) && [:agent, *(:out if again)].include?(state_of(it)) }.map do |item|
+        latest = latest(item)
+        sent_back = {ownerReply: reopened(item)&.slice(:kind, :text), previousResponse: (latest&.result if reopened(item))}.compact
+        {**item, source: {**item[:source], reviewedHead: reviewed_head(item, latest)}, **sent_back}
+      end
+    end
+
+    # The head the request was last looked at on: the one its last answer
+    # names, or the one the owner reviewed.
+    def reviewed_head(item, latest)
+      source = item[:source]
+      latest&.result&.dig(:head).presence || source[:reviewedHead].presence || source.dig(:decision, :head).presence || source[:head]
+    end
+
+    # The owner's reply that sent an answered request back to the agent.
+    def reopened(item) = reply_to(item)&.then { it if it[:resolution] == "reopened" }
+
+    def ids_in(*states) = everything.select { in_focus?(it[:pr]) && states.include?(state_of(it)) }.pluck(:id)
+
+    # The requests that stand now: notes and code comments, the owner's
+    # choices, and what they asked beside the decisions.
+    def current = @current ||= [*requests, *choices.map { choice_item(it) }, *asked_beside.reject { it[:withdrawn] }]
+
+    # Those, and what an earlier batch carried that came back answered.
+    def everything
+      @everything ||= current + batches.flat_map { it[:items] }.select { latest(it) }.uniq { it[:id] }.reject { |item| current.any? { it[:id] == item[:id] } }
+    end
+
+    def notes_of(marked, pr:)
+      @burst.marks(marked).notes.select(&:open?).map do |note|
+        {id: "note:#{note.id}", pr:, kind: note.kind, text: note.text,
+         source: {kind: "note", noteId: note.id, anchor: note.place&.to_h, head: @route.at(pr)&.head_oid}}
+      end
+    end
+
+    def choice_item(choice)
+      {id: choice.request_id, pr: choice.pr, kind: choice.kind, text: choice.text,
+       source: {kind: "decision", decision: choice.decision, needsReview: stale?(choice)}}
+    end
+
+    def asked_beside = @asked_beside ||= Array(@document["requests"]).map(&:deep_symbolize_keys)
+
+    def archived?(item)
+      (item[:pr] && !heads.key?(item[:pr])) || asked_beside.any? { it[:id] == item[:id] && it[:withdrawn] } ||
+        (item.dig(:source, :kind) == "decision" && choices.none? { it.request_id == item[:id] }) ||
+        (item[:kind] == "leave" && item.dig(:source, :decision, :id).to_s.start_with?("missing:"))
+    end
+
+    # The batch that last carried a request as it stands, with the owner's
+    # last reply to it when they reopened it.
+    def carrier(item)
+      reply = reopened(item)
+      batches.rfind do |batch|
+        batch[:items].any? { it[:id] == item[:id] && signature(it) == signature(item) && (!reply || it[:ownerReply]&.values_at(:kind, :text) == reply.values_at(:kind, :text)) }
+      end
+    end
+
+    # Taken by a pass that no answer came back to yet.
+    def out?(item)
+      batch = carrier(item)
+      batch && responses.none? { it[:batchId] == batch[:id] }
+    end
+
+    # The answer that stands for a request: the newest, or the one the
+    # owner confirmed, or, once they replied, the one that came after.
+    def latest(item)
+      (@latest ||= {}).fetch([item[:id], signature(item)]) do |key|
+        answers = answers_to(item)
+        reply = reply_to(item)
+        replied_to = answers.find { it.key == reply[:replyTo] } if reply
+        @latest[key] = case reply&.dig(:resolution)
+        when "confirmed" then replied_to || answers.max_by(&:newness)
+        when "reopened" then answers.select { after?(it, reply) }.max_by(&:newness) || replied_to || answers.max_by(&:newness)
+        else answers.max_by(&:newness)
+        end
+      end
+    end
+
+    def answers_to(item)
+      responses.filter_map do |response|
+        batch = batches.find { it[:id] == response[:batchId] }
+        request = batch[:items].find { it[:id] == item[:id] }
+        result = response[:results].find { it[:id] == item[:id] }
+        Answer.new(response:, result:, batch:, request:, order: batches.index(batch)) if request && result && signature(request) == signature(item)
+      end
+    end
+
+    def after?(answer, reply)
+      Rounds.moment(answer.batch[:createdAt]) >= Rounds.moment(reply[:at]) && answer.request[:ownerReply]&.values_at(:kind, :text) == reply.values_at(:kind, :text)
+    end
+
+    # The owner's last word on a request, while it is about the request as
+    # it stands: one about earlier words is no longer theirs to it.
+    def reply_to(item)
+      reply = @document.dig("feedback", item[:id])&.deep_symbolize_keys
+      reply if reply && intent_of(reply) == signature(item)
+    end
+
+    def intent_of(reply)
+      JSON.parse(reply[:intent].to_s)
+    rescue JSON::ParserError
+    end
+
+    def signature(item) = [item[:kind], item[:text]]
+
+    # Every batch a handover carried, the oldest first: those the pages keep,
+    # and those the desk wrote that no page has taken in yet.
+    def batches
+      @batches ||= [*Array(@document["batches"]), *Handover.kept(@burst).map(&:batch)].map(&:deep_symbolize_keys)
+        .uniq { it[:id] }.sort_by { Rounds.moment(it[:createdAt]) }
+    end
+
+    # Every answer that came back to a batch the desk knows, as the page
+    # takes them in: a response naming a request its batch did not carry is
+    # refused whole. One written again under a new time is a newer version
+    # of it, and both are kept.
+    def responses
+      @responses ||= [*Array(@document["responses"]), *ResponseFiles.new(@burst).all].map(&:deep_symbolize_keys).uniq { it.values_at(:id, :createdAt) }.select do |response|
+        asked = batches.find { it[:id] == response[:batchId] }&.dig(:items)&.pluck(:id)
+        ids = response[:results].pluck(:id)
+        asked && ids.uniq.size == ids.size && (ids - asked).empty?
+      end
+    end
+
+    # Every decision of the burst as it reads now.
+    def placed = @placed ||= @route.flat_map { |stop| stop.description.decisions.map { Placed.new(stop:, decision: it) } }
+
+    def choices = @choices ||= kept("choices", "choice")
+
+    def drafts = @drafts ||= kept("pending", "draft")
+
+    # Each entry with the decision it was made on, as the page's reconcile()
+    # finds it: by its key, or by its words where it has none, and never one
+    # decision for two entries.
+    def kept(field, kind)
+      claimed = Set.new
+      Array(@document[field]).map do |entry|
+        was = entry["decision"]
+        matches = placed.select { it.pr == was["pr"] && (was["key"] ? it.decision.key == was["key"] : [it.decision.lead, it.decision.text] == was.values_at("lead", "text")) }
+        at = matches.first if matches.one? && claimed.add?(matches.first.id)
+        Choice.new(entry:, request_id: entry["requestId"] || "#{kind}:#{was["id"]}:#{entry["savedAt"] || "legacy"}", at:)
+      end
+    end
+
+    # A choice no longer stands once its decision changed under it, unless
+    # the owner confirmed what came back of it, or its pull request left.
+    def stale?(choice)
+      return false if confirmed?(choice) || !heads.key?(choice.pr)
+
+      decision = choice.at&.decision || reading_as(choice)
+      !(decision && @kept.stands?(choice.entry, decision))
+    end
+
+    # The one decision of its pull request that reads as the choice's did.
+    def reading_as(choice)
+      was = choice.entry["decision"]
+      placed.select { it.pr == choice.pr && [it.decision.lead, it.decision.bare_text] == [was["lead"], Theme.unmarked(was["text"])] }.then { it.first.decision if it.one? }
+    end
+
+    def confirmed?(choice)
+      item = {id: choice.request_id, kind: choice.kind, text: choice.text}
+      reply_to(item)&.then { it[:resolution] == "confirmed" && latest(item)&.key == it[:replyTo] }
+    end
+
+    def in_focus?(pr) = @focus.whole? || (!pr.nil? && @focus.at(pr).present?)
+
+    # The choices a handover carries, in the burst's order.
+    def in_order(kept) = kept.select { in_focus?(it.pr) }.sort_by { |choice| placed.index { it.id == choice.decision[:id] } || placed.size }
+
+    def left_at_once
+      in_order(choices).select { it.in_bulk? && !stale?(it) }.group_by(&:pr)
+        .map { |pr, left| {pr:, decisions: left.map { {id: it.decision[:id], lead: it.decision[:lead]} }} }
+    end
+
+    # One answer given to several decisions, as a copy for each part it
+    # touches, carried out once at its earliest pull request there.
+    def answered_together
+      choices.select { it.together && !stale?(it) }.group_by(&:together).flat_map do |batch, answered|
+        copies = answered.group_by { @route.at(it.pr)&.part&.to_param || it.pr }.values.map do |here|
+          sorted = here.sort_by { |choice| @route.find_index { it.number == choice.pr } || 0 }
+          {words: @route.at(sorted.first.pr)&.part&.in_words || "##{sorted.first.pr}", at: sorted.first.pr,
+           decisions: sorted.map { {id: it.decision[:id], pr: it.pr, lead: it.decision[:lead]} }}
+        end
+        copies.select { in_focus?(it[:at]) }.map { |copy| {batch:, kind: answered.first.kind, text: answered.first.entry["text"], **copy, elsewhere: copies - [copy]} }
+      end
+    end
+
+    def unfinished_drafts = drafts.select { in_focus?(it.pr) }.map { {**it.entry.deep_symbolize_keys, requestId: it.request_id, decision: it.decision} }
+
+    # What the owner has not reviewed yet, or not since it changed under
+    # their choice: no instruction, only what they have not reached.
+    def unreviewed
+      placed.select { in_focus?(it.pr) }.filter_map do |decision|
+        choice = choices.find { it.decision[:id] == decision.id }
+        {id: decision.id, pr: decision.pr, lead: decision.decision.lead, **(choice ? {changed: true} : {})} if choice.nil? || stale?(choice)
+      end
+    end
+  end
+end

data/app/models/proctolog/route.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # The order to take a burst in, part by part: each of GitHub's native stacks
+  # the burst names, from the bottom up by GitHub's own positions; then each
+  # chain found from a top by following base branches down; then the pull
+  # requests that stand alone.
+  #
+  # A pull request shows once: a stack holds it before a chain does, and a
+  # chain before it stands alone. A chain that meets a pull request placed
+  # before it stops there and sits on it, so a change below is still carried
+  # up through it: #1085 sits on #1062, the top of stack #1055.
+  class Route
+    include Enumerable
+
+    # A piece of a burst the owner can take on its own. Its id is its stack's
+    # number, its top's number, or "alone": GitHub never gives a stack and a
+    # pull request the same number. A chain that sits on another part names
+    # that part's id as `above`.
+    Part = Data.define(:id, :kind, :above) do
+      def self.stack(number) = new(id: number, kind: :stack, above: nil)
+
+      def self.chain(top, above: nil) = new(id: top, kind: :chain, above:)
+
+      def self.alone = new(id: "alone", kind: :alone, above: nil)
+
+      def stack? = kind == :stack
+
+      def alone? = kind == :alone
+
+      # As a sentence names it: "stack #1055", "the chain up to #1086".
+      def in_words
+        if alone? then "the pull requests that stand alone"
+        elsif stack? then "stack ##{id}"
+        else "the chain up to ##{id}"
+        end
+      end
+
+      def to_param = id.to_s
+    end
+
+    # A pull request in its place: its layer of `of` within its part, and the
+    # number of the pull request it sits on, nil at the bottom of a stack, of
+    # a chain on nothing, and for one that stands alone.
+    Stop = Data.define(:pull_request, :layer, :of, :part, :on) do
+      delegate :number, :title, :url, :base, :description, :files, :head_oid, :described_at, :committed_at, :open_threads, to: :pull_request
+
+      def initialize(part: Part.alone, on: nil, **) = super
+
+      def stacked? = of > 1 || !on.nil?
+    end
+
+    # `stacks` are the native stacks the burst names, `tops` the tops of the
+    # chains it follows, `loose` the pull requests it names to stand alone.
+    # `kept` holds each stack's members, bottom first, as they were last
+    # read: a stack is taken from it when GitHub could not say where its pull
+    # requests stand.
+    def initialize(among:, tops: [], stacks: [], loose: [], kept: {})
+      @stacks, @tops, @loose, @kept = stacks, tops, loose, kept
+      @pull_requests = among.index_by(&:number)
+      @by_head = among.index_by(&:head)
+    end
+
+    def each(&) = stops.each(&)
+
+    def parts = stops.map(&:part).uniq
+
+    def stops_of(part) = select { it.part == part }
+
+    def part(id) = parts.find { it.to_param == id.to_s }
+
+    def at(number) = stops_by_number[number]
+
+    # Whether GitHub said where its pull requests stand in its stacks: when it
+    # did not, a stack's members are those kept from its last reading.
+    def stacks_known? = @pull_requests.each_value.all?(&:stack_known?)
+
+    # The stops on either side of one, in the order of the route.
+    def before(stop) = each_cons(2).find { |_, later| later == stop }&.first
+
+    def after(stop) = each_cons(2).find { |earlier, _| earlier == stop }&.last
+
+    # What a layer sits on, in its own part or one before it, and the first
+    # that sits on it.
+    def under(stop) = stop.on&.then { at(it) }
+
+    def over(stop) = find { it.on == stop.number }
+
+    # Every layer that sits on it, however far up and in whichever part,
+    # nearest first.
+    def above(stop) = select { |other| below(other).include?(stop) }
+
+    # The other stops that change files this one changes, each with those files.
+    def sharing_files_with(stop) = others_than(stop).index_with { it.files & stop.files }.compact_blank
+
+    # The other stops its description names.
+    def named_by(stop) = others_than(stop).select { stop.description.mentions.include?(it.number) }
+
+    # Pull requests the burst names that are no longer open: merged, or closed.
+    def gone = (@tops + @loose) - @pull_requests.keys
+
+    private
+
+    def others_than(stop) = reject { it == stop }
+
+    def stops_by_number = @stops_by_number ||= index_by(&:number)
+
+    # What a stop stands on, down to the bottom it rests on.
+    def below(stop) = Enumerator.produce(stop) { under(it) || raise(StopIteration) }.drop(1)
+
+    def stops
+      @stops ||= {}.then do |placed|
+        [*@stacks.map { native(it, placed) }, *@tops.map { chain(it, placed) }, alone(placed)].flatten.compact
+      end
+    end
+
+    # A native stack's members by their positions, or as they were last read.
+    def native(number, placed)
+      members = stacks_known? ? @pull_requests.each_value.select { it.stack == number }.sort_by(&:position) : @pull_requests.values_at(*@kept.fetch(number, [])).compact
+      layers(members.reject { placed.key?(it.number) }, Part.stack(number), placed)
+    end
+
+    # Followed down from its top until a base is not the branch of an open
+    # pull request, or is that of one placed already, which it then sits on.
+    # A top with nothing under it and nothing to sit on stands alone.
+    def chain(top, placed)
+      pull_request = @pull_requests[top]
+      return if pull_request.nil? || placed.key?(top)
+
+      followed = Enumerator.produce(pull_request) { @by_head.fetch(it.base) { raise StopIteration } }.take_while { !placed.key?(it.number) }
+      on = @by_head[followed.last.base]&.then { placed[it.number] }
+      return if followed.one? && on.nil?
+
+      layers(followed.reverse, Part.chain(top, above: on&.part&.id), placed, on: on&.number)
+    end
+
+    def alone(placed)
+      singles = (@tops + @loose).filter_map { @pull_requests[it] }.uniq.reject { placed.key?(it.number) }
+      singles.map { place(Stop.new(pull_request: it, layer: 1, of: 1, part: Part.alone, on: nil), placed) }
+    end
+
+    # Each layer sits on the one under it, and the first on `on`.
+    def layers(pull_requests, part, placed, on: nil)
+      pull_requests.each.with_index(1).map do |pull_request, layer|
+        place(Stop.new(pull_request:, layer:, of: pull_requests.size, part:, on: (layer == 1) ? on : pull_requests[layer - 2].number), placed)
+      end
+    end
+
+    def place(stop, placed) = (placed[stop.number] = stop)
+  end
+end

data/app/models/proctolog/rules.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # The rules the owner made of answers in a burst. Each is a request of its
+  # own in the choices document, made from a choice and attached to it, so
+  # the agent's answer to a rule never answers the choice. The pages' script
+  # makes a rule and hands it over; the burst page lists them, and edits or
+  # withdraws one here. A rule is as far as its request: written, sent,
+  # answered, confirmed, followed as review-rounds.js follows every request.
+  class Rules
+    include Enumerable
+
+    Missing = Class.new(Failure)
+    Blank = Class.new(Failure)
+
+    # A decision a rule was made from, as the choice named it.
+    From = Data.define(:pr, :lead)
+
+    # A rule as the burst page shows it. `replaces` is the line the agent
+    # recorded before an edit, until the replacement is handed over.
+    Rule = Data.define(:id, :pr, :text, :from, :state, :replaces) do
+      def to_param = id
+
+      def withdrawn? = state == :withdrawn
+
+      def within?(focus) = focus.whole? || from.any? { focus.at(it.pr) }
+    end
+
+    # `handovers` are those the desk kept: a pass an agent took itself is
+    # in no page's choices until a page takes its batch in.
+    def initialize(choices, handovers: [])
+      @choices, @handovers = choices, handovers
+    end
+
+    def each(&) = requests.map { rule(it) }.each(&)
+
+    def find(id) = detect { it.id == id } || raise(Missing, "This burst has no rule #{id}.")
+
+    # A rule the agent does not have yet changes where it stands. One it has
+    # changes too, and says which line it replaces until that is handed over.
+    def edit(id, text)
+      text = text.to_s.squish.presence or raise Blank, "A rule is one line: write it, or withdraw the rule."
+
+      write(id) do |rule, _|
+        rule["text"] = text
+        sent = last_sent(id)&.fetch("text")
+        (sent && sent != text) ? rule["replaces"] = sent : rule.delete("replaces")
+      end
+    end
+
+    # A rule the agent does not have yet goes. One it has stays, withdrawn,
+    # and an ordinary request asks the agent to take it out again.
+    def withdraw(id)
+      write(id) do |rule, requests|
+        next requests.delete(rule) unless (sent = last_sent(id))
+
+        rule["withdrawn"] = true
+        requests << {"id" => "request:#{SecureRandom.uuid}", "pr" => rule["pr"], "kind" => "change",
+                     "text" => "Withdraw the rule \"#{sent["text"]}\" (#{id}): take it out of where you recorded it, and name that file as evidence.",
+                     "source" => {"kind" => "rule_withdrawn", "rule" => id}}
+      end
+    end
+
+    private
+
+    def document = @choices.document || {}
+
+    def requests = Array(document["requests"]).select { it["kind"] == "rule" }
+
+    def batches = [*Array(document["batches"]), *@handovers.map(&:batch)].uniq { it["id"] }.sort_by { Rounds.moment(it["createdAt"]) }
+
+    def rule(request)
+      Rule.new(id: request["id"], pr: request["pr"], text: request["text"], replaces: request["replaces"], state: state_of(request),
+        from: Array(request.dig("source", "decisions")).map { From.new(pr: it["pr"], lead: it["lead"]) })
+    end
+
+    # Written until a handover holds it in these words; answered once the
+    # agent's response to that handover does; confirmed once the owner said
+    # so of these words. The owner sending it back makes it written again.
+    def state_of(request)
+      return :withdrawn if request["withdrawn"]
+
+      said = said_of(request)
+      return :confirmed if said&.dig("resolution") == "confirmed"
+
+      since = (Time.iso8601(said["at"]) if said&.dig("resolution") == "reopened")
+      held = handed_over(request).select { since.nil? || Time.iso8601(it["createdAt"]) >= since }
+      return :answered if held.any? { answered_in?(it, request) }
+
+      held.any? ? :sent : :written
+    end
+
+    # The owner's last word on what came back, while it is on these words.
+    def said_of(request)
+      said = document.dig("feedback", request["id"]) or return
+      said if intent_of(said) == [request["kind"], request["text"]]
+    end
+
+    def intent_of(said)
+      JSON.parse(said["intent"].to_s)
+    rescue JSON::ParserError
+    end
+
+    def handed_over(request) = batches.select { |batch| batch["items"].any? { it["id"] == request["id"] && it["text"] == request["text"] } }
+
+    def answered_in?(batch, request) = Array(document["responses"]).any? { |report| report["batchId"] == batch["id"] && report["results"].any? { it["id"] == request["id"] } }
+
+    # The rule as the agent last had it.
+    def last_sent(id) = batches.flat_map { it["items"] }.rfind { it["id"] == id }
+
+    # Changes the kept document, numbered past the writing it changes so a
+    # page left open catches up with it rather than writing over it.
+    def write(id)
+      changed = document.deep_dup
+      requests = changed["requests"] ||= []
+      rule = requests.find { it["id"] == id && it["kind"] == "rule" } or raise Missing, "This burst has no rule #{id}."
+      yield rule, requests
+      @choices.keep(changed.merge("revision" => @choices.revision + 1))
+    end
+  end
+end