task_progress 0.0.1

data/sig/generated/task_progress.rbs

@@ -0,0 +1,553 @@
+# Generated from lib/task_progress.rb with RBS::Inline
+
+# Hierarchical progress for task trees. A TaskProgress is a handle onto one node of a tree; the
+# tree itself is a Log of change events, applied and numbered under one lock, which outputs
+# receive in order - to draw a terminal, write to a pipe, stream to a browser, or feed a Mount
+# that grafts the tree under a node of a tree in another process.
+#
+#     TaskProgress.cli("Import") do |root|
+#       root.subtask("Download", unit: "bytes") { |t| t.track_io(io) ... }
+#       root.subtask("Rows", total: rows.size) { |t| rows.each { import(it); t.tick } }
+#     end
+class TaskProgress
+  # A task's place in the tree: its ancestors' ids, then its own - `[]` is the root
+  type path = Array[String]
+
+  # Anything that takes the batches a log commits, in order - a lambda will do
+  interface _Output
+    def call: (Batch batch, Log log) -> void
+  end
+
+  type output = Object & _Output
+
+  PARTS: String
+
+  # Ractors on Ruby 3.4 corrupt the VM's table of call sites: a `super` from Ruby into a C
+  # constructor (Data#initialize, say) while Ractors run brings the process down, sometimes
+  # minutes later and in unrelated code. Ruby 4.0 has it fixed, and the Ractor::Port API with it
+  RACTORS: bool
+
+  # Loads every part now rather than on first use - before forking workers, say, so they share
+  # the loaded code. TrackedIO is left out when the progressive_io gem is not there, and
+  # JobSerializer when ActiveJob is not
+  # : () -> singleton(TaskProgress)
+  def self.eager_load!: () -> singleton(TaskProgress)
+
+  OPTIONAL: Array[Symbol]
+
+  # Raised at whoever works on a task that was called off, so the work stops at its next step.
+  # An Exception rather than a StandardError, like Interrupt: a `rescue => e` around one step
+  # should not swallow it and carry on with the next
+  class Canceled < Exception
+    # The task that was called off
+    attr_reader task: TaskProgress
+
+    # For the task that was called off, and what it is called
+    # : (TaskProgress, ?String) -> void
+    def initialize: (TaskProgress, ?String) -> void
+  end
+
+  # The log the task's tree lives in
+  attr_reader log: Log
+
+  # The task's place in the tree - `[]` for the root
+  attr_reader path: path
+
+  ROOT: path
+
+  # A root reporting wherever suits a command-line program: a parent process, when it handed
+  # one down in TASK_PROGRESS_FD; a redrawn tree on a terminal; an ExecutionLog on CI or when
+  # piped. With a block, it runs the block as the root's work and returns its value
+  # : (?String, ?io: IO | StringIO, ?quiet: bool, **untyped) -> TaskProgress
+  # : [T] (?String, ?io: IO | StringIO, ?quiet: bool, **untyped) { (TaskProgress) -> T } -> T?
+  def self.cli: (?String, ?io: IO | StringIO, ?quiet: bool, **untyped) -> TaskProgress
+              | [T] (?String, ?io: IO | StringIO, ?quiet: bool, **untyped) { (TaskProgress) -> T } -> T?
+
+  # The output `cli` and `bar` pick for where the program runs, or nil when `quiet`
+  # : (io: IO | StringIO, quiet: bool) -> output?
+  def self.cli_output: (io: IO | StringIO, quiet: bool) -> output?
+
+  # A single bar, the way progress bars always worked: no block, and it finishes by itself once
+  # its count reaches `total`. Without a total it counts and spins. The last frame is drawn at
+  # exit, finished or not
+  #
+  #     bar = TaskProgress.bar("Importing", total: rows.size)
+  #     rows.each { import(it) && bar.tick }
+  # : (?String, ?total: Integer?, ?io: IO | StringIO, ?quiet: bool, **untyped) -> TaskProgress
+  def self.bar: (?String, ?total: Integer?, ?io: IO | StringIO, ?quiet: bool, **untyped) -> TaskProgress
+
+  # A root nobody runs a block for is finished when the program ends: done if it ends well,
+  # failed with the error if it is going down with one
+  # : (TaskProgress, output?) -> TaskProgress
+  def self.finish_at_exit: (TaskProgress, output?) -> TaskProgress
+
+  # Outputs that hold a thread or a screen - TerminalOutput, ExecutionLogOutput, BufferedOutput -
+  # can be closed, to draw their last and stop
+  # : (output?) -> void
+  def self.close: (output?) -> void
+
+  # A root whose tree is drawn in pages with Turbo, from wherever it runs - a job, say. Every
+  # frame is the whole tree as HTML (see HTMLRenderer), sent as a Turbo Stream at most every
+  # `interval` seconds, and kept in `store` for a page to draw before the first one arrives.
+  # Cancel buttons post to `cancel_url`; the request waits in `store`, where this checks for it
+  # every `poll` seconds - so it works across processes too. With a block, the block is the
+  # root's work, as with `cli`.
+  #
+  #     TaskProgress.broadcast(csv_import, "Importing") { |root| ... }   # in a Rails job
+  #     <%= task_progress_tree @csv_import %>                              # in its page
+  #
+  # In Rails, the target is a record, and the rest comes from RailsDefaults: Turbo::StreamsChannel,
+  # Rails.cache and the route the Railtie adds. Outside Rails the target is the element's id, and
+  # `to:` - called with each frame - is up to you
+  # : (untyped, ?String, ?to: (^(String) -> void)?, ?store: TurboStreamOutput::_Store?, ?tokens: Token?, ?cancel_url: String?, ?renderer: TurboStreamOutput::_Renderer?, ?interval: Integer | Float, ?poll: Integer | Float, **untyped) -> TaskProgress
+  # : [T] (untyped, ?String, ?to: (^(String) -> void)?, ?store: TurboStreamOutput::_Store?, ?tokens: Token?, ?cancel_url: String?, ?renderer: TurboStreamOutput::_Renderer?, ?interval: Integer | Float, ?poll: Integer | Float, **untyped) { (TaskProgress) -> T } -> T?
+  def self.broadcast: (untyped, ?String, ?to: (^(String) -> void)?, ?store: TurboStreamOutput::_Store?, ?tokens: Token?, ?cancel_url: String?, ?renderer: TurboStreamOutput::_Renderer?, ?interval: Integer | Float, ?poll: Integer | Float, **untyped) -> TaskProgress
+                    | [T] (untyped, ?String, ?to: (^(String) -> void)?, ?store: TurboStreamOutput::_Store?, ?tokens: Token?, ?cancel_url: String?, ?renderer: TurboStreamOutput::_Renderer?, ?interval: Integer | Float, ?poll: Integer | Float, **untyped) { (TaskProgress) -> T } -> T?
+
+  # Picks up the requests CancellationsApp leaves in the store, until the root has ended. A store
+  # that fails for a moment is tried again at the next poll
+  # : (TaskProgress, TurboStreamOutput::_Store, String, Integer | Float) -> Thread
+  def self.watch_cancellations: (TaskProgress, TurboStreamOutput::_Store, String, Integer | Float) -> Thread
+
+  # Where handed-off trees are kept, unless a call says otherwise - one connection, as
+  # `Rails.cache` is, and every tree in it a stream of its own under its own key.
+  #
+  #     TaskProgress.stream_store = TaskProgress::RedisStreamStore.new(RedisClient.config(url: ENV["REDIS_URL"]).new_pool)
+  #
+  # Until it is set, a MemoryStreamStore: trees kept in this process alone, which is right for
+  # development and tests and quietly wrong anywhere a job runs in another process. So in
+  # production (RAILS_ENV, RACK_ENV or APP_ENV) it raises instead - set it to a MemoryStreamStore
+  # yourself if this process alone is what you mean
+  # : () -> untyped
+  def self.stream_store: () -> untyped
+
+  # Sets where handed-off trees are kept, see `stream_store`
+  # : (untyped) -> void
+  def self.stream_store=: (untyped) -> void
+
+  # Sets what signs the links `for_page` hands out. In Rails, the Railtie sets the app's own,
+  # made from its `secret_key_base`
+  # : (Token?) -> void
+  def self.tokens=: (Token?) -> void
+
+  # Where TreesApp is mounted, for `for_page` to link to - `/task_progress/trees` by default
+  # : () -> String
+  def self.trees_path: () -> String
+
+  # Sets where TreesApp is mounted
+  # : (String) -> void
+  def self.trees_path=: (String) -> void
+
+  # What signs the links `for_page` hands out - see `tokens=`
+  # : () -> Token
+  def self.tokens: () -> Token
+
+  # Everything a page needs to show a handed-off tree, as plain JSON-ready data - a prop for an
+  # Inertia or React page, a data attribute for Stimulus:
+  #
+  #     render inertia: "Videos/Show", props: {progress: TaskProgress.for_page(video.progress_key)}
+  #     # => {events: "/task_progress/trees/…/events", poll: "…/poll", cancel: "…/cancellations",
+  #     #     snapshot: {v: 1, …}}
+  #
+  # The links carry a Token good for `expires_in` seconds, not the tree's key: hand this out only
+  # where the page may see that tree. `snapshot` is the tree as it stands, so the page draws it
+  # before anything has come down the stream. TreesApp answers the links
+  # : (String | TaskProgress, ?expires_in: Integer, ?stream_store: untyped) -> Hash[Symbol, untyped]
+  def self.for_page: (String | TaskProgress, ?expires_in: Integer, ?stream_store: untyped) -> Hash[Symbol, untyped]
+
+  # A root to hand to whoever does the work - a job, a worker, another machine - which takes it
+  # up with `adopt`. Until then it waits, as "pending", where anyone can `follow` it: a page can
+  # show the job queued before any worker has picked it up.
+  #
+  #     import = TaskProgress.handoff("Importing", cancelable: true)
+  #     ImportJob.perform_later(upload, import)        # ActiveJob takes the task itself
+  #     Importer.perform_async(upload.id, import.key)  # anything else, its key
+  #
+  # The tree lives in `stream_store`, under `key`. Once it is handed off, leave it to the worker: what
+  # this side writes after the worker has started is ignored
+  # : (String, ?stream_store: untyped, **untyped) -> TaskProgress
+  def self.handoff: (String, ?stream_store: untyped, **untyped) -> TaskProgress
+
+  # Takes up a tree handed off with `handoff` - by its key, or the task itself - as a root of
+  # its own, with the name and attributes it was handed off with. It starts the tree over: a
+  # second worker to adopt it, a job retried, replaces what the last one wrote.
+  #
+  # Batches go out squashed, every `interval` seconds at most. Every `heartbeat` seconds it tells
+  # whoever follows that it is alive, and takes the cancel requests that came. With a block,
+  # the block is the root's work, see `run`, and it all stops when the block returns. Without
+  # one, call `log.close` once the work is over - ActiveJob does this by itself, see JobSerializer
+  # : (String | TaskProgress, ?stream_store: untyped, ?heartbeat: Integer | Float, ?interval: Integer | Float) -> TaskProgress
+  # : [T] (String | TaskProgress, ?stream_store: untyped, ?heartbeat: Integer | Float, ?interval: Integer | Float) { (TaskProgress) -> T } -> T?
+  def self.adopt: (String | TaskProgress, ?stream_store: untyped, ?heartbeat: Integer | Float, ?interval: Integer | Float) -> TaskProgress
+                | [T] (String | TaskProgress, ?stream_store: untyped, ?heartbeat: Integer | Float, ?interval: Integer | Float) { (TaskProgress) -> T } -> T?
+
+  # Draws the tree handed off at `key` where a command-line program draws one (see `cli`) until it
+  # finishes, and returns it. Ctrl-C stops watching, and leaves the work alone. What
+  # `task_progress watch` does
+  # : (String, ?stream_store: untyped, ?io: IO | StringIO) -> TaskProgress
+  def self.watch: (String, ?stream_store: untyped, ?io: IO | StringIO) -> TaskProgress
+
+  # A tree that mirrors the one in `stream_store` at `key`, kept up to date on a thread of its own -
+  # for drawing it anywhere: a terminal, a parent's tree, an endpoint of your own. Requests to
+  # cancel its tasks go to whoever writes it; it goes stale when the writer goes quiet, and fails
+  # after `give_up_after` seconds of that, see Mount#follow_stream. With a block, it follows for
+  # as long as the block runs; without one, `log.close` stops it. SSE and Poll take the key
+  # itself, and follow for as long as they need to. A key nothing was handed off at is a KeyError
+  # : (String, ?stream_store: untyped, ?poll: Integer | Float, ?give_up_after: Integer | Float) -> TaskProgress
+  # : [T] (String, ?stream_store: untyped, ?poll: Integer | Float, ?give_up_after: Integer | Float) { (TaskProgress) -> T } -> T
+  def self.follow: (String, ?stream_store: untyped, ?poll: Integer | Float, ?give_up_after: Integer | Float) -> TaskProgress
+                 | [T] (String, ?stream_store: untyped, ?poll: Integer | Float, ?give_up_after: Integer | Float) { (TaskProgress) -> T } -> T
+
+  # The tree in `stream_store` at `key` as it is now, read once - for a page, or one poll, that needs
+  # no more than that. See `follow` for one kept up to date. A key nothing was handed off at -
+  # or whose tree has expired - is a KeyError, as with Hash#fetch
+  # : (String, ?stream_store: untyped) -> TaskProgress
+  def self.fetch: (String, ?stream_store: untyped) -> TaskProgress
+
+  # Runs the block as the work of every root among `arguments` that a worker took up with `adopt`
+  # - done when it returns, failed when it raises - and closes them after. What JobSerializer
+  # wraps every ActiveJob in; for any other job runner, wrap `perform` in it the same way
+  # : [T] (Array[untyped]) { () -> T } -> T?
+  def self.working_on: [T] (Array[untyped]) { () -> T } -> T?
+
+  # The block as the work of each root in turn, the first outermost
+  # : [T] (Array[TaskProgress]) { () -> T } -> T?
+  def self.within: [T] (Array[TaskProgress]) { () -> T } -> T?
+
+  # A root that is a mount and nothing else, named after `key` until the stream says otherwise
+  # : (String, untyped) -> [TaskProgress, Mount]
+  def self.mirror: (String, untyped) -> [ TaskProgress, Mount ]
+
+  # A size that is cheap to know, or nil - never `count`, which would run a lazy enumerator
+  # : (untyped) -> Integer?
+  def self.size_of: (untyped) -> Integer?
+
+  # Where the browser client lives: `task_tree.js` (the fold, and `follow` for an SSE stream),
+  # `render_queue.js`, `row_view.js`, a Stimulus controller, a React component and
+  # `task_tree.css`. No build step - serve the directory as it is, under any prefix
+  # : () -> String
+  def self.js_path: () -> String
+
+  # Copies the browser client into `dir`, for a bundler - Vite, esbuild - to take from there, and
+  # returns the names of the files it wrote. The copy is a package of its own, named
+  # `task_progress`: `npm install ./dir` puts it in `node_modules`, TypeScript declarations and all.
+  #
+  # `dir` is the gem's: whatever an earlier vendoring left there is replaced, so a file the gem
+  # no longer ships goes too. A directory with files of its own in it is left alone, and raises
+  # : (String) -> Array[String]
+  def self.vendor_js: (String) -> Array[String]
+
+  # The version of the client vendored into `dir`, or nil when there is none
+  # : (String) -> String?
+  def self.vendored_js_version: (String) -> String?
+
+  # A silent root, for a library's default
+  # : (?String) -> TaskProgress
+  def self.null: (?String) -> TaskProgress
+
+  # A new tree, and its root. See `subtask` for `autofinish`
+  # : (?String, ?outputs: Array[output], ?log: Log, ?total: Integer?, ?expect: Integer?, ?indeterminate: bool, ?unit: String?, ?cancelable: bool, ?autofinish: bool) -> void
+  def initialize: (?String, ?outputs: Array[output], ?log: Log, ?total: Integer?, ?expect: Integer?, ?indeterminate: bool, ?unit: String?, ?cancelable: bool, ?autofinish: bool) -> void
+
+  # The attributes an `open` carries, without what is at its default
+  # : (name: String, ?total: Integer?, ?weight: (Integer | Float)?, ?expect: Integer?, ?indeterminate: bool, ?unit: String?, ?cancelable: bool, ?attempt: Integer?) -> Hash[Symbol, untyped]
+  def self.attributes: (name: String, ?total: Integer?, ?weight: (Integer | Float)?, ?expect: Integer?, ?indeterminate: bool, ?unit: String?, ?cancelable: bool, ?attempt: Integer?) -> Hash[Symbol, untyped]
+
+  # A handle on the task at `path` in `log`, without opening anything
+  # : (Log, path) -> TaskProgress
+  def self.handle: (Log, path) -> TaskProgress
+
+  # The stream key a root from `handoff`, `adopt`, `follow` or `fetch` lives under, which is
+  # all it takes to `adopt` or `follow` it from anywhere. Nil for any other task
+  # : () -> String?
+  def key: () -> String?
+
+  # The task and everything under it as plain Hashes - its name, status and percent, and its
+  # count, total, message and error where it has them - for a test to compare, or a log line:
+  #
+  #     {name: "Import", status: :done, percent: 100, children: [
+  #       {name: "Rows", status: :failed, percent: 40, count: 4, total: 10, error: "RuntimeError: row 5"}]}
+  # : () -> Hash[Symbol, untyped]
+  def outline: () -> Hash[Symbol, untyped]
+
+  # The node at `path` in `state` as an outline, see TaskProgress#outline
+  # : (State, path) -> Hash[Symbol, untyped]
+  def self.outline: (State, path) -> Hash[Symbol, untyped]
+
+  # Which run of the work this is, for a root taken up with `adopt`: 1, then 2 for a retry, and
+  # so on. Drawn with the task from 2 on. Nil for any other task
+  # : () -> Integer?
+  def attempt: () -> Integer?
+
+  # The task as the tree holds it now - frozen, and safe to read from any thread
+  # : () -> Node
+  def node: () -> Node
+
+  # What it is called
+  # : () -> String
+  def name: () -> String
+
+  # `:pending`, `:active`, `:done`, `:failed` or `:canceled`
+  # : () -> Symbol
+  def status: () -> Symbol
+
+  # A whole percent, 100 only once it and everything under it are done
+  # : () -> Integer
+  def percent: () -> Integer
+
+  # How far along, 0.0..1.0, unrounded
+  # : () -> Float
+  def fraction: () -> Float
+
+  # The latest thing it said, see `note`
+  # : () -> String?
+  def message: () -> String?
+
+  # What it failed with: `class`, `message`, `backtrace` and `cause`, see `fail!`
+  # : () -> Hash[Symbol, untyped]?
+  def error: () -> Hash[Symbol, untyped]?
+
+  # How many it has counted, see `advance`
+  # : () -> Integer
+  def count: () -> Integer
+
+  # How many it counts to, or nil when it has no total
+  # : () -> Integer?
+  def total: () -> Integer?
+
+  # Done, and everything under it ended
+  # : () -> bool
+  def complete?: () -> bool
+
+  # Ended by `fail!`
+  # : () -> bool
+  def failed?: () -> bool
+
+  # Ended by `cancel!`, or by a task above it being canceled
+  # : () -> bool
+  def canceled?: () -> bool
+
+  # Whether a reader may offer to call it off, and it has not ended yet
+  # : () -> bool
+  def cancelable?: () -> bool
+
+  # The task at `path` under this one - an Array of ids, or the ids joined with a dash, the way
+  # the browser client keys its rows (`x3k0-00af`) - or nil
+  # : (path | String) -> TaskProgress?
+  def find: (path | String) -> TaskProgress?
+
+  # Ended, by `done!`, `fail!` or `cancel!` - whether or not everything under it did
+  # : () -> bool
+  def finished?: () -> bool
+
+  # The task it is under, or nil for the root
+  # : () -> TaskProgress?
+  def parent: () -> TaskProgress?
+
+  # The root of its tree
+  # : () -> TaskProgress
+  def root: () -> TaskProgress
+
+  # The tasks directly under it, in the order they opened
+  # : () -> Array[TaskProgress]
+  def subtasks: () -> Array[TaskProgress]
+
+  # Sends this task's subtree to an output, as a tree of its own rooted at `[]` - for the root
+  # that is the whole tree. See Log#add_output
+  # : (?output?, ?replay: bool) ?{ (Batch, Log) -> void } -> output
+  def add_output: (?output?, ?replay: bool) ?{ (Batch, Log) -> void } -> output
+
+  # Stops sending to an output, as it was given to `add_output`
+  # : (output) -> void
+  def remove_output: (output) -> void
+
+  # A child task. `total:` makes it counted (drive it with `advance`), `indeterminate: true`
+  # one with no measure of its own, and `weight:` how much of the parent it is. With a block
+  # it runs the block as the child's work, see `run`, and returns the block's value.
+  #
+  # A counted task is done once its count reaches its total. Give it `autofinish: false` when
+  # the total is a guess, and the work may go past it.
+  #
+  # `cancelable: true` tells whoever draws the tree that it may offer to call the task off - see
+  # `find` and `cancel!` for taking that request back
+  # : (String, ?total: Integer?, ?weight: (Integer | Float)?, ?expect: Integer?, ?indeterminate: bool, ?unit: String?, ?cancelable: bool, ?autofinish: bool) -> TaskProgress
+  # : [T] (String, ?total: Integer?, ?weight: (Integer | Float)?, ?expect: Integer?, ?indeterminate: bool, ?unit: String?, ?cancelable: bool, ?autofinish: bool) { (TaskProgress) -> T } -> T?
+  def subtask: (String, ?total: Integer?, ?weight: (Integer | Float)?, ?expect: Integer?, ?indeterminate: bool, ?unit: String?, ?cancelable: bool, ?autofinish: bool) -> TaskProgress
+             | [T] (String, ?total: Integer?, ?weight: (Integer | Float)?, ?expect: Integer?, ?indeterminate: bool, ?unit: String?, ?cancelable: bool, ?autofinish: bool) { (TaskProgress) -> T } -> T?
+
+  # Runs the block as this task's work: done when it returns, failed with the error when it
+  # raises - an Interrupt or a SignalException included - and the error raised on. A task
+  # canceled ends its work quietly: `run` returns nil. One canceled before it began does not
+  # begin
+  # : [T] () { (TaskProgress) -> T } -> T?
+  def run: [T] () { (TaskProgress) -> T } -> T?
+
+  # Moves the percent; 100 finishes the task
+  # : (Integer | Float, ?message: String?) -> self
+  def update: (Integer | Float, ?message: String?) -> self
+
+  # Adds to the count - finishing the task, if that reaches its total
+  # : (?Integer, ?message: String?) -> self
+  def advance: (?Integer, ?message: String?) -> self
+
+  # Adds one to the count, see `advance`
+  # : (?message: String?) -> self
+  def tick: (?message: String?) -> self
+
+  # Goes through a collection a step per item. Given a name it opens a subtask for it, and
+  # otherwise counts on this task. The total comes from `size`, never `count` - so a lazy
+  # enumerator stays lazy, and one with no size just counts. Done when the loop ends, failed
+  # with the error if the block raises. Without a block it returns an Enumerator, which does
+  # the same as it is consumed
+  #
+  #     root.iterate(files, "Files") { |file| copy(file) }
+  #     root.iterate(rows, "Rows").map { transform(it) }
+  # : (Enumerable[untyped], ?String?, ?total: Integer?, ?step: Integer) ?{ (untyped) -> untyped } -> untyped
+  def iterate: (Enumerable[untyped], ?String?, ?total: Integer?, ?step: Integer) ?{ (untyped) -> untyped } -> untyped
+
+  # Prints a line above the tree, where it stays. It changes nothing in the tree itself, so a
+  # reader joining later never sees it - like anything said on a terminal
+  # : (_ToS) -> self
+  def puts: (_ToS) -> self
+
+  # The latest thing it says, shown on its row
+  # : (String?) -> self
+  def note: (String?) -> self
+
+  # Changes what it counts to
+  # : (Integer?) -> void
+  def total=: (Integer?) -> void
+
+  # Renames it
+  # : (String) -> void
+  def name=: (String) -> void
+
+  # Finishes the task, and with it every task under it still open - each with a `done` of its
+  # own, deepest first, in the same batch. The work they were part of is over, and a reader
+  # should not be left waiting on a task nobody will ever finish. What was mounted is left to
+  # its Mount
+  # : (?String?) -> self
+  def done!: (?String?) -> self
+
+  # Fails the task with an exception, a message, or nothing. `extra` goes along with the error:
+  # up to 8 of them, each true, false or an Integer, which is all a reader takes
+  #
+  # What is still open under it is canceled: it did not fail, it was cut short
+  # : (?(Exception | String)?, **bool | Integer) -> self
+  def fail!: (?(Exception | String)?, **bool | Integer) -> self
+
+  # Calls the task off, and every task still open under it, each with a `cancel` of its own -
+  # from any thread. Whoever works on one of them next gets a Canceled, which `run` takes as
+  # the end of that task's work. Canceling a finished task does nothing
+  # : (?String?) -> self
+  def cancel!: (?String?) -> self
+
+  # Calls the block with the reason once this task is canceled, see Log#on_cancel. For work that
+  # blocks and so would not notice a cancel until it next touches its task:
+  #
+  #     rows.on_cancel { http.finish }
+  # : () { (String?) -> void } -> self
+  def on_cancel: () { (String?) -> void } -> self
+
+  # Asks for the task at `path` under this one to be canceled - the way a request from outside
+  # (a browser, a parent process) comes in. Everything is decided in one transaction against the
+  # tree as it stands, so it cannot race the task finishing. Returns:
+  #
+  #     :canceled   it was, along with everything still open under it
+  #     :forwarded  it lives in a mounted child, which was asked; its cancel comes back up the stream
+  #     :moot       there is nothing left to cancel - no such task, or it has already ended
+  #     :refused    it is not cancelable
+  #
+  # A request that comes too late is moot, not an error: by the time it arrives the task may well
+  # have finished, and its process exited
+  # : (path | String, ?String?) -> Symbol
+  def request_cancel: (path | String, ?String?) -> Symbol
+
+  # Reads cancel requests off an IO - one JSON line each, `{"cancel": [ids], "reason": "..."}` -
+  # on a thread of its own, and hands them to `request_cancel`. This is the far end of a Mount's
+  # control pipe; anything malformed is skipped. Returns the thread, which ends at EOF.
+  #
+  # The root itself, `[]`, is what the parent mounted, and only the parent asks for it: the
+  # mount was ended there, so the root is canceled whether it is cancelable or not
+  # : (IO) -> Thread
+  def accept_cancel_requests: (IO) -> Thread
+
+  # Takes one cancel request - a line as `accept_cancel_requests` reads them - and returns what
+  # came of it, see `request_cancel`; nil for a line that is not a request
+  # : (String) -> Symbol?
+  def take_cancel_request: (String) -> Symbol?
+
+  # The reason an Interrupt gives, if it gives one: Ctrl-C raises it saying "Interrupt", and a
+  # SIGINT from outside saying nothing at all
+  # : (Interrupt) -> String?
+  def self.interrupted_by: (Interrupt) -> String?
+
+  # Every task called off carries the reason, so each of them can say why it stopped
+  # : (Transaction, path, String?) -> void
+  def self.cancel_in: (Transaction, path, String?) -> void
+
+  # Everything the block does to the tree lands as one batch, or none of it does
+  # : [T] () { (TaskProgress) -> T } -> T
+  def transaction: [T] () { (TaskProgress) -> T } -> T
+
+  # A child whose subtree is fed from elsewhere - a subprocess, a Ractor, a stream. Only the
+  # Mount writes under it, see Mount
+  # : (String, ?weight: (Integer | Float)?, ?cancelable: bool) -> Mount
+  def mount: (String, ?weight: (Integer | Float)?, ?cancelable: bool) -> Mount
+
+  # Wraps an IO so that reading it advances this task by the bytes read, see TrackedIO. The total
+  # is the IO's size unless given; with neither, the task counts bytes with no measure. With a
+  # block, the block runs with the wrapped IO as this task's work, see `run`. Needs the
+  # progressive_io gem, and an IO that can tell its position - for a pipe or a socket, call
+  # `advance` with each chunk instead
+  # : (untyped, ?total: Integer?, ?step: Integer?) -> TrackedIO
+  # : [T] (untyped, ?total: Integer?, ?step: Integer?) { (TrackedIO) -> T } -> T?
+  def track_io: (untyped, ?total: Integer?, ?step: Integer?) -> TrackedIO
+              | [T] (untyped, ?total: Integer?, ?step: Integer?) { (TrackedIO) -> T } -> T?
+
+  # The same task in the same tree
+  # : (untyped) -> bool
+  def ==: (untyped) -> bool
+
+  # Equal handles hash alike, so a task works as a Hash key
+  # : () -> Integer
+  def hash: () -> Integer
+
+  # Its path, name and status
+  # : () -> String
+  def inspect: () -> String
+
+  SCALE: Array[[ String, Integer ]]
+
+  # "4.2s", "3m07s", "2h15m"
+  # : (Integer | Float) -> String
+  def self.duration: (Integer | Float) -> String
+
+  # "142 KB", "2.9 MB", "640 bytes" - a whole number drops its decimal
+  # : (Integer | Float) -> String
+  def self.human_bytes: (Integer | Float) -> String
+
+  # Every message reaches the tree as valid UTF-8. Messages often name files, and a raw
+  # ZIP read hands those back tagged ASCII-8BIT, so a "Reading Alice’s.xhtml" would
+  # otherwise blow up whatever an output writes to (a database column, a UTF-8 log line)
+  # : (nil) -> nil
+  # : (untyped) -> String
+  def self.utf8: (nil) -> nil
+               | (untyped) -> String
+
+  private
+
+  # : (**untyped) -> self
+  def meta: (**untyped) -> self
+
+  # Finishing a finished task is a no-op; anything else on one raises, as does writing under
+  # a mount from here
+  # : (Transaction, ?finishing: bool) -> bool
+  def writable!: (Transaction, ?finishing: bool) -> bool
+
+  # : (State, ?above: bool) -> bool
+  def sealed?: (State, ?above: bool) -> bool
+
+  # : (untyped) -> bool
+  def positioned?: (untyped) -> bool
+end