task_progress 0.0.1

data/lib/task_progress/cancellations_app.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "json"
+require "uri"
+
+class TaskProgress
+  # A Rack app that takes the cancel buttons HTMLRenderer draws, for a tree that lives in another
+  # process - a job broadcasting with TaskProgress.broadcast. It cannot cancel anything itself:
+  # it checks the request's token, and leaves the request in the store the job watches. The job
+  # decides, as it does for any request (see TaskProgress#request_cancel), and the cancel comes
+  # back in its next frame.
+  #
+  # A Turbo form submission is answered with an empty Turbo Stream, which changes nothing on the
+  # page - the frame that follows does. Anything else gets 202 and a little JSON
+  class CancellationsApp
+    # How long a request waits for its run to take it up
+    REQUEST_TTL = 600 #: Integer
+    # @rbs @store: TurboStreamOutput::_Store
+    # @rbs @tokens: Token
+
+    # Leaves requests in `store`, for tokens `tokens` issued
+    #: (store: TurboStreamOutput::_Store, tokens: Token) -> void
+    def initialize(store:, tokens:)
+      @store = store
+      @tokens = tokens
+    end
+
+    # Takes a POST with `path` - the task's ids joined with a dash - and `token`, as a form or JSON
+    #: (Hash[String, untyped]) -> [Integer, Hash[String, String], Array[String]]
+    def call(env)
+      return respond(405, {error: "POST a cancellation"}) unless env["REQUEST_METHOD"] == "POST"
+      params = CancellationsApp.params(env)
+      key = @tokens.verify(params["token"]&.to_s) or return respond(403, {error: "invalid or expired token"})
+      path = params["path"].to_s.split("-")
+      return respond(422, {error: "malformed path"}) unless path.length <= Wire::MAX_DEPTH && path.all? { it.match?(Wire::SEGMENT) }
+      # A request nobody takes up - the run ended first - is forgotten after a while
+      @store.write(CancellationsApp.request_key(key, path), "Canceled from the browser", expires_in: REQUEST_TTL)
+      return [200, {"content-type" => "text/vnd.turbo-stream.html"}, [""]] if env["HTTP_ACCEPT"].to_s.include?("turbo-stream")
+      respond(202, {path: path.join("-"), state: "requested"})
+    end
+
+    # Where a request to cancel the task at `path` waits, for the tree stored under `key`
+    #: (String, path) -> String
+    def self.request_key(key, path) = "#{key}/cancel/#{path.join("-")}"
+
+    # The request's parameters, from a form or JSON
+    #: (Hash[String, untyped]) -> Hash[String, untyped]
+    def self.params(env) # :nodoc:
+      # Mounted in Rails, a middleware (Rack::MethodOverride, looking for `_method`) has read a
+      # form's body already - and left it parsed here
+      form = env["rack.request.form_hash"]
+      return form if form.is_a?(Hash)
+      input = env["rack.input"]
+      input.rewind if input.respond_to?(:rewind)
+      body = input&.read(4096).to_s
+      if env["CONTENT_TYPE"].to_s.include?("json")
+        parsed = begin
+          JSON.parse(body)
+        rescue
+          nil
+        end
+        parsed.is_a?(Hash) ? parsed : {}
+      else
+        URI.decode_www_form(body).to_h
+      end
+    rescue ArgumentError
+      {}
+    end
+
+    private
+
+    #: (Integer, Hash[Symbol, untyped]) -> [Integer, Hash[String, String], Array[String]]
+    def respond(status, body) = [status, {"content-type" => "application/json"}, [JSON.generate(body)]]
+  end
+end

data/lib/task_progress/event.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+class TaskProgress
+  # One change to one node. `path` leads to the node by its ancestors' ids - `[]` is the root,
+  # `["x3k0", "00af"]` a child of the root's child "x3k0". Each id is four random base36
+  # characters, unique among its siblings and never the task's name: names repeat, and they
+  # may say more than should leave the process
+  #
+  # The ops:
+  #     open   {name, total, weight, expect, indeterminate, unit} - a new node
+  #     meta   any of open's keys, and `stale` - attributes changed after the fact
+  #     set    a percent, 0..100
+  #     add    a delta to the node's count
+  #     note   a message
+  #     done   nil
+  #     fail   an error hash, see Wire.error_to_h
+  #     cancel a reason, or nil - the work was called off, and did not fail
+  #     prune  nil - drop every descendant of the node
+  #     put    a whole node, see Node#to_h - what a squashed log is made of
+  #     say    a line to print, which changes nothing in the tree - so a squash drops it, the
+  #            way a terminal's scrollback is gone once a program exits
+  # @rbs skip
+  Event = Data.define(:path, :op, :value)
+
+  # @rbs!
+  #   class Event < Data
+  #     attr_reader path: path
+  #     attr_reader op: Symbol
+  #     attr_reader value: untyped
+  #     def self.new: (path: path, op: Symbol, ?value: untyped) -> instance
+  #     def with: (?path: path, ?op: Symbol, ?value: untyped) -> instance
+  #   end
+
+  class Event
+    # An event for the node at `path` - its path is frozen, so the event can be shared
+    #: (path: path, op: Symbol, ?value: untyped) -> void
+    def initialize(path:, op:, value: nil)
+      # RBS has no keywords for Data#initialize, which takes them all the same
+      super(path: path.frozen? ? path : path.dup.freeze, op:, value:) # steep:ignore
+    end
+  end
+
+  # Every op there is - see Event
+  OPS = %i[open meta set add note done fail cancel prune put say].freeze #: Array[Symbol]
+end

data/lib/task_progress/execution_log_output.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+class TaskProgress
+  # For a CI log, or anything else that is read top to bottom after the fact: one finished
+  # line per thing worth saying, never a redraw, each line led by the overall percent and
+  # the time since the root opened.
+  #
+  #     [ 42%  1m02s] Import › Rows: row 12000
+  #     [ 50%  1m10s] ✓ Import › Rows  8.1s
+  #     [ 50%  1m11s] ✗ Import › Engine: watermarking failed
+  #     [ 50%  1m12s] ⊘ Import › Publish: Ctrl-C
+  #
+  # A task finishing, failing or being canceled, and a line it `puts`, go out at once and every
+  # time - though of a task and the ones under it ending in one batch, only the task says so. The
+  # rest - notes and counts - are only ever the latest news, so it says at most one of those
+  # per `interval`, the newest. With nothing to say for `heartbeat` it says it is still
+  # going, so a CI runner watching for output does not take a long quiet step for a hang
+  class ExecutionLogOutput
+    # @rbs @io: IO | StringIO
+    # @rbs @interval: Integer | Float
+    # @rbs @heartbeat: Integer | Float
+    # @rbs @clock: ^() -> Float
+    # @rbs @lock: Thread::Mutex
+    # @rbs @wake: Thread::ConditionVariable
+    # @rbs @log: Log?
+    # @rbs @pending: [path, String?]?
+    # @rbs @said_at: Float
+    # @rbs @closed: bool
+    # @rbs @thread: Thread?
+    # @rbs @ended: Set[path]
+
+    # Writes to `io`: news at most every `interval` seconds, and that it is still going after `heartbeat` seconds of quiet
+    #: (?IO | StringIO, ?interval: Integer | Float, ?heartbeat: Integer | Float, ?clock: ^() -> Float) -> void
+    def initialize(io = $stderr, interval: 3.0, heartbeat: 60.0, clock: -> { Process.clock_gettime(Process::CLOCK_REALTIME) })
+      @io = io
+      @interval = interval
+      @heartbeat = heartbeat
+      @clock = clock
+      @lock = Mutex.new
+      @wake = ConditionVariable.new
+      @log = nil
+      @pending = nil
+      @said_at = -Float::INFINITY
+      @closed = false
+      @thread = nil
+      @ended = Set.new
+    end
+
+    # Takes one batch, see Log#add_output
+    #: (Batch, Log) -> void
+    def call(batch, log)
+      @lock.synchronize do
+        return if @closed
+        @log = log
+        @said_at = @clock.call - @interval if @said_at.infinite? # the first news goes out at once
+        snapshot = log.snapshot
+        events = batch.events.map { ending_put(it) || it }
+        endings = events.filter_map { it.path if ENDINGS.include?(it.op) }
+        events.each do |event|
+          case event.op
+          when *ENDINGS
+            # News from inside a task that has ended is old news
+            @pending = nil if @pending&.first&.take(event.path.length) == event.path
+            next unless @ended.add?(event.path)
+            next if endings.any? { it.length < event.path.length && event.path.take(it.length) == it }
+            say(snapshot, ending(snapshot, event))
+          when :say then say(snapshot, "#{names(snapshot, event.path)}: #{event.value}")
+          when :note then @pending = [event.path, event.value] if event.value
+          when :set, :add then @pending = [event.path, nil] unless @pending&.first == event.path
+          end
+        end
+        # Older news than the ending. Judged by what came, never the snapshot, which can run ahead
+        # of delivery - and close before the batch that ends the root has been said
+        return close_locked(flush: false) if @ended.include?([])
+        say_pending if @pending && @clock.call - @said_at >= @interval
+        @thread ||= Thread.new { run }
+        @wake.signal
+      end
+    end
+
+    # Says what is still pending, and stops
+    #: () -> void
+    def close
+      @lock.synchronize { close_locked }
+      @thread&.join
+    end
+
+    private
+
+    #: () -> void
+    def run
+      @lock.synchronize do
+        until @closed
+          due = @pending ? @said_at + @interval : @said_at + @heartbeat
+          wait = due - @clock.call
+          next @wake.wait(@lock, wait) if wait.positive?
+          next say_pending if @pending
+          snapshot = @log&.snapshot or next
+          say(snapshot, "#{snapshot[[]]&.name}: still going")
+        end
+      end
+    end
+
+    #: (?flush: bool) -> void
+    def close_locked(flush: true)
+      return if @closed
+      say_pending if flush && @pending && @log
+      @closed = true
+      @wake.signal
+    end
+
+    #: () -> void
+    def say_pending
+      pending = @pending or return
+      path, message = pending
+      @pending = nil
+      snapshot = @log&.snapshot or return
+      node = snapshot[path] or return
+      say(snapshot, message ? "#{names(snapshot, path)}: #{message}" : "#{names(snapshot, path)}#{count(node)}")
+    end
+
+    #: (State, String) -> void
+    def say(snapshot, text)
+      root = snapshot[[]]
+      elapsed = root ? @clock.call - root.opened_at : 0
+      @io.puts(format("[%3d%% %6s] %s", snapshot.percent, TaskProgress.duration(elapsed), text))
+      @io.flush
+      @said_at = @clock.call
+    end
+
+    ENDINGS = %i[done fail cancel].freeze #: Array[Symbol]
+    PUT_ENDINGS = {done: :done, failed: :fail, canceled: :cancel}.freeze #: Hash[Symbol, Symbol]
+    private_constant :ENDINGS, :PUT_ENDINGS
+
+    # A squashed batch - from BufferedOutput, a stream, a mount catching up - says a task ended by
+    # putting it whole, finished. Said once, like the ending it stands for
+    #: (Event) -> Event?
+    def ending_put(event)
+      op = PUT_ENDINGS[event.value[:status]] if event.op == :put
+      return unless op && !@ended.include?(event.path)
+      Event.new(path: event.path, op:, value: if op == :fail
+                                                event.value[:error]
+                                              else
+                                                ((op == :cancel) ? event.value[:message] : nil)
+                                              end)
+    end
+
+    #: (State, Event) -> String
+    def ending(snapshot, event)
+      names = names(snapshot, event.path)
+      case event.op
+      when :done then "✓ #{names}#{took(snapshot[event.path])}"
+      when :fail then "✗ #{names}: #{event.value&.dig(:message)}"
+      else "⊘ #{names}#{": #{event.value}" if event.value}"
+      end
+    end
+
+    # The task's name, after the names of every task it is under
+    #: (State, path) -> String
+    def names(snapshot, path) = (0..path.length).filter_map { snapshot[path.take(it)]&.name }.join(" › ")
+
+    #: (Node) -> String
+    def count(node)
+      total = node.total
+      return "" unless total || node.count.positive?
+      bytes = node.unit == "bytes"
+      shown = bytes ? TaskProgress.human_bytes(node.count) : node.count.to_s
+      total = (bytes ? TaskProgress.human_bytes(total) : total.to_s) if total
+      " #{[shown, total].compact.join("/")}"
+    end
+
+    # A task that reported nothing before it finished started when it finished, as far as the
+    # tree knows - so it took as long as it was open
+    #: (Node?) -> String
+    def took(node)
+      return "" unless node && (finished = node.finished_at)
+      started = node.started_at
+      from = (started && started < finished) ? started : node.opened_at
+      "  #{TaskProgress.duration(finished - from)}"
+    end
+  end
+end

data/lib/task_progress/fold.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+class TaskProgress
+  # Siblings drawn as one row, see below
+  Fold = Data.define(
+    :status, #: Symbol
+    :count #: Integer
+  )
+
+  # Siblings drawn as one row - "✓ 9,812 more done", "· 340 more waiting" - so a task with ten
+  # thousand children draws as a handful of rows. See State#rows, which makes them
+  class Fold
+    # What the row says
+    #: () -> String
+    def name = "#{count.to_s.gsub(/\B(?=(\d{3})+(?!\d))/, ",")} more #{(status == :done) ? "done" : "waiting"}"
+  end
+end

data/lib/task_progress/html_renderer.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "cgi/escape"
+
+class TaskProgress
+  # Draws a tree as HTML - the same rows, with the same classes, as the browser client's renderers
+  # draw, so `task_tree.css` styles both and a page can move from one to the other unchanged.
+  # This is what TurboStreamOutput sends, and what TurboSSE streams.
+  #
+  # Elapsed times are `<task-progress-clock>` elements (`task_progress_clock.js`), which tick on
+  # between frames; everything else is as it was when the tree was drawn. A cancelable task gets
+  # a cancel button that is a plain form, posting the task's path and `cancel_token` to
+  # `cancel_url` - so it needs no JavaScript, and Turbo submits it without leaving the page.
+  #
+  # To draw rows your own way, subclass it and override `row`, or hand TurboStreamOutput anything
+  # that answers `id` and `render(snapshot, from = [])` - say, an object that renders a partial
+  class HTMLRenderer
+    # A circle with a cross in it, drawn in the row's text color - the same in every font
+    CANCEL_ICON = '<svg viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"><circle cx="8" cy="8" r="6.25" fill="none" stroke="currentColor" stroke-width="1.5"/><path d="M5.6 5.6l4.8 4.8M10.4 5.6l-4.8 4.8" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/></svg>' #: String
+
+    GLYPHS = {done: "✓", failed: "✗", canceled: "⊘", pending: "·"}.freeze #: Hash[Symbol, String]
+    private_constant :GLYPHS
+
+    # The id of the element the tree is drawn in - what a Turbo Stream targets
+    attr_reader :id #: String
+
+    # @rbs @cancel_url: String?
+    # @rbs @cancel_token: String?
+    # @rbs @clock: ^() -> Float
+
+    # Draws into an element with the id `id`. Without a `cancel_url`, no task offers a cancel
+    # button. `clock` is for tests to pin down
+    #: (id: String, ?cancel_url: String?, ?cancel_token: String?, ?clock: ^() -> Float) -> void
+    def initialize(id:, cancel_url: nil, cancel_token: nil, clock: -> { Process.clock_gettime(Process::CLOCK_REALTIME) })
+      @id = id
+      @cancel_url = cancel_url
+      @cancel_token = cancel_token
+      @clock = clock
+    end
+
+    # The whole tree in its element - or the subtree at `from`, drawn as a tree of its own
+    #: (State, ?path) -> String
+    def render(snapshot, from = [])
+      rows = snapshot.rows(from).map do |path, node|
+        depth = path.length - from.length
+        node.is_a?(Fold) ? fold(path, node, depth:) : row(snapshot, path, node, depth:)
+      end
+      %(<div id="#{h(@id)}" class="tree" data-task-progress-at="#{@clock.call}">#{rows.join}</div>)
+    end
+
+    # One task's row, `depth` levels in
+    #: (State, path, Node, ?depth: Integer) -> String
+    def row(snapshot, path, node, depth: path.length)
+      status = (node.status == :done && !snapshot.complete?(path)) ? :active : node.status
+      glyph = GLYPHS[status]
+      icon = glyph ? "<span>#{glyph}</span>" : '<span class="spin"></span>'
+      indeterminate = !!(node.children.empty? && node.indeterminate && node.status == :active)
+      percent = snapshot.percent(path)
+      classes = ["row", status, ("stale" if node.stale)].compact.join(" ")
+      <<~HTML.delete("\n")
+        <div class="#{classes}" id="#{h(@id)}-#{h(path.empty? ? "root" : path.join("-"))}" data-path="#{h(path.join("-"))}">
+        <div class="label" style="padding-left: #{depth * 18}px">
+        <span class="icon">#{icon}</span><span class="name">#{h(node.name)}</span><span class="message">#{h(message(node))}</span>
+        </div>
+        <div class="bar#{" indeterminate" if indeterminate}"><span style="width: #{percent}%"></span></div>
+        #{cancel(path, node)}
+        <div class="measure">#{measure(path, node, percent, indeterminate)}</div>
+        </div>
+      HTML
+    end
+
+    # Siblings folded into one row, see State#rows - drawn as a row like any other, so the
+    # columns line up
+    #: (path, Fold, ?depth: Integer) -> String
+    def fold(path, fold, depth: path.length)
+      done = fold.status == :done
+      <<~HTML.delete("\n")
+        <div class="row folded #{done ? "done" : "pending"}" id="#{h(@id)}-#{h(path.join("-"))}" data-path="#{h(path.join("-"))}">
+        <div class="label" style="padding-left: #{depth * 18}px">
+        <span class="icon"><span>#{GLYPHS[done ? :done : :pending]}</span></span><span class="name">#{h(fold.name)}</span><span class="message"></span>
+        </div>
+        <div class="bar"><span style="width: #{done ? 100 : 0}%"></span></div>
+        <span class="cancel-slot"></span>
+        <div class="measure"></div>
+        </div>
+      HTML
+    end
+
+    private
+
+    #: (String?) -> String
+    def h(text) = CGI.escapeHTML(text.to_s)
+
+    #: (Node) -> String
+    def message(node)
+      said = (node.status == :failed) ? node.error&.dig(:message) : [pace(node), node.message].compact.reject(&:empty?).join(" · ")
+      [("attempt #{node.attempt}" if node.attempt.to_i > 1), said].compact.reject(&:empty?).join(" · ")
+    end
+
+    # The rate over the run so far, and the time left at it
+    #: (Node) -> String?
+    def pace(node)
+      started = node.started_at
+      return nil unless node.status == :active && node.children.empty? && started && node.count.positive?
+      seconds = @clock.call - started
+      return nil if seconds < 1
+      rate = node.count / seconds
+      per = if node.unit == "bytes"
+        "#{TaskProgress.human_bytes(rate)}/s"
+      else
+        ((rate < 10) ? format("%.1f/s", rate) : "#{rate.floor}/s")
+      end
+      total = node.total
+      return per unless total && total > node.count
+      "#{per}, #{TaskProgress.duration((total - node.count) / rate)} left"
+    end
+
+    #: (path, Node, Integer, bool) -> String
+    def measure(path, node, percent, indeterminate)
+      total = node.total
+      if node.children.empty? && total
+        (node.unit == "bytes") ? "#{TaskProgress.human_bytes(node.count)} / #{TaskProgress.human_bytes(total)}" : "#{node.count} / #{total}"
+      elsif indeterminate
+        clock(node)
+      else
+        "#{percent}%"
+      end
+    end
+
+    # Ticks on in the browser between frames, from the time the tree was drawn
+    #: (Node) -> String
+    def clock(node)
+      started = node.started_at or return ""
+      seconds = [(node.finished_at || @clock.call) - started, 0].max
+      ended = %( finished="#{node.finished_at}") if node.finished_at
+      %(<task-progress-clock started="#{started}" drawn="#{@clock.call}"#{ended}>#{format("%.1fs", seconds)}</task-progress-clock>)
+    end
+
+    # The cancel column is there on every row, so the bars line up
+    #: (path, Node) -> String
+    def cancel(path, node)
+      return '<span class="cancel-slot"></span>' unless @cancel_url && node.cancelable && !node.finished?
+      <<~HTML.delete("\n")
+        <form class="cancel-slot" action="#{h(@cancel_url)}" method="post" data-turbo="true">
+        <input type="hidden" name="path" value="#{h(path.join("-"))}">
+        <input type="hidden" name="token" value="#{h(@cancel_token)}">
+        <button type="submit" class="cancel" aria-label="Cancel #{h(node.name)}">#{CANCEL_ICON}</button>
+        </form>
+      HTML
+    end
+  end
+end

data/lib/task_progress/job_serializer.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+# ActiveJob's own serializers name Duration, DateTime and the rest as they load, and only Rails
+# loads those first - so outside Rails all of ActiveSupport has to come along
+require "active_support/all"
+require "active_job"
+
+class TaskProgress
+  # Lets a tree from TaskProgress.handoff go to an ActiveJob as an argument like any other - no
+  # ids to pass, nothing to look up:
+  #
+  #     progress = TaskProgress.handoff("Importing", cancelable: true)
+  #     ImportJob.perform_later(csv_import, progress)
+  #
+  #     class ImportJob < ApplicationJob
+  #       def perform(csv_import, progress)
+  #         progress.subtask("Rows", total: csv_import.rows.size) { |rows| ... }
+  #       end
+  #     end
+  #
+  # It goes into the queue as its key. Out of the queue it comes adopted - see TaskProgress.adopt -
+  # and the job's work is the root's: done when `perform` returns, failed when it raises, and a
+  # cancel stops it without failing the job. A retry adopts it anew, as attempt 2, and starts
+  # it over. The Railtie installs all of this; without Rails, call `install` once ActiveJob loads.
+  #
+  # Only a root that was handed off can go: a task that lives in this process alone has nowhere
+  # for a worker elsewhere to write to
+  class JobSerializer < ActiveJob::Serializers::ObjectSerializer
+    # Teaches ActiveJob to take trees as arguments, and runs every job that gets one as the tree's work
+    def self.install
+      ActiveJob::Serializers.add_serializers(self)
+      ActiveJob::Base.prepend(Performing)
+      ActiveJob::Base.around_perform do |job, perform|
+        TaskProgress.working_on(job.arguments) do
+          perform.call
+          # A `before_perform` that halts stops the chain inside this one: the work never ran
+          job.task_progress_halted!
+        end
+      end
+    end
+
+    # Arguments are taken up as they are deserialized, which is before `around_perform` - and a job
+    # can stop in between: an argument that cannot be found, a `before_perform` that halts. Every
+    # tree taken up for a job is seen to the end once the job is through, whatever became of it,
+    # so none of them is left beating for work that is not being done
+    module Performing
+      # A callback halted the job - ActiveSupport says so through this hook
+      def halted_callback_hook(*)
+        @task_progress_halted = true
+        super
+      end
+
+      # Fails the trees the job took up, if a callback halted it before its work
+      def task_progress_halted!
+        return unless @task_progress_halted
+        arguments.flat_map { it.is_a?(Hash) ? it.values : [it] }.grep(TaskProgress).each do |root|
+          root.fail!("The job stopped before it began its work") unless root.finished?
+        end
+      end
+
+      # Runs the job, and ends what it took up and did not end
+      def perform_now
+        (Thread.current[:task_progress_adopted] ||= []).push([])
+        super
+      ensure
+        adopted = Thread.current[:task_progress_adopted]&.pop || []
+        adopted.each do |root|
+          root.fail!($! || "The job stopped before it began its work") unless root.finished?
+          root.log.close
+        end
+      end
+    end
+
+    # Whether it is a TaskProgress
+    def serialize?(argument) = argument.is_a?(TaskProgress)
+
+    # Its key, and nothing else
+    def serialize(task)
+      key = task.key or raise ActiveJob::SerializationError,
+        "#{task.inspect} lives in this process alone - hand a tree to a job with TaskProgress.handoff"
+      super("key" => key)
+    end
+
+    # The tree at the key, adopted
+    def deserialize(hash)
+      TaskProgress.adopt(hash.fetch("key")).tap { Thread.current[:task_progress_adopted]&.last&.push(it) }
+    end
+
+    # What it serializes
+    def klass = TaskProgress
+  end
+end

data/lib/task_progress/journal.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+class TaskProgress
+  # The changes one transaction made, so that it can be undone whole
+  class Journal # :nodoc:
+    # @rbs @saved: Hash[path, [Node, Integer]?]
+
+    #: () -> void
+    def initialize = @saved = {}
+
+    # Remembers the node as it was before the transaction first touched it - nil for one it opened.
+    # A shallow copy, and how many children it had: a transaction only ever adds children at the
+    # end, or swaps the list for a new one, so that is enough to put the list back - and a parent
+    # of a hundred thousand tasks is not copied whole every time one of them moves
+    #: (path, Node?) -> void
+    def touch(path, node)
+      @saved[path] = (node && [node.dup, node.children.length]) unless @saved.key?(path)
+    end
+
+    # Every path it touched, opened or removed
+    #: () -> Array[path]
+    def paths = @saved.keys
+
+    #: (Hash[path, Node]) -> void
+    def rollback(nodes)
+      @saved.each do |path, saved|
+        next nodes.delete(path) unless saved
+        node, length = saved
+        node.children.slice!(length..)
+        nodes[path] = node
+      end
+    end
+  end
+end