asgard 0.4.0 → 0.5.0

data/lib/asgard/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Asgard
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/lib/asgard/watch/changes.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Asgard
+  # The files a watcher trigger saw change, as three lists of paths relative
+  # to the project root. The watcher hands them to the task through three
+  # environment variables (newline-separated, since paths may hold spaces
+  # or colons); the `changes` Kernel method reads them back. Every list is
+  # empty when the task is run by hand, so one task body serves both.
+  class Changes < Data.define(:modified, :added, :removed)
+    VARIABLES = { modified: "ASGARD_MODIFIED", added: "ASGARD_ADDED", removed: "ASGARD_REMOVED" }.freeze
+
+    class << self
+      # The changes behind this process, read once from ENV. Tests and a
+      # watcher-run task that re-execs call forget to read them again.
+      def current = @current ||= from_env
+
+      def forget = @current = nil
+
+      # Parses the trigger variables; a missing one is an empty list.
+      def from_env(env = ENV) = new(**VARIABLES.to_h { |member, variable| [member, env[variable].to_s.split("\n")] })
+    end
+
+    def initialize(modified: [], added: [], removed: [])
+      super(modified: modified.map(&:to_s).freeze, added: added.map(&:to_s).freeze, removed: removed.map(&:to_s).freeze)
+    end
+
+    # Every changed path once, in modified, added, removed order.
+    def all = (modified + added + removed).uniq
+
+    def empty? = modified.empty? && added.empty? && removed.empty?
+
+    # The trigger variables that reproduce this object through from_env.
+    def to_env = VARIABLES.to_h { |member, variable| [variable, public_send(member).join("\n")] }
+  end
+
+  module Watch
+    # Which Changes member each events: kind fills. Listen reports the first
+    # kind as "modified".
+    EVENT_MEMBERS = { changed: :modified, added: :added, removed: :removed }.freeze
+
+    module_function
+
+    # A listener batch ({ modified:, added:, removed: }) narrowed to the
+    # kinds in events (a Set from normalize_events), as a Changes; nil
+    # when nothing is left, so the dispatcher skips the trigger.
+    def filter_events(batch, events)
+      kept    = EVENT_MEMBERS.to_h { |event, member| [member, events.include?(event) ? Array(batch[member]) : []] }
+      changes = Changes.new(**kept)
+      changes.empty? ? nil : changes
+    end
+  end
+end

data/lib/asgard/watch/commands.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "shellwords"
+require "time"
+
+# warn is silent when $VERBOSE is nil and bypasses $stderr in Ruby 4.0 (see
+# base/task_dsl.rb); these messages are for the user, so they always print.
+# rubocop:disable Style/StderrPuts
+
+module Asgard
+  module Watch
+    # `asgard watcher SUBCOMMAND` — runs and manages the watcher for the
+    # entries declared with `watch :task, paths: ...` in a .loki file.
+    # Subclasses Asgard::Base rather than Tasks so `asgard watcher help`
+    # lists only these subcommands, not every project task.
+    class Commands < Asgard::Base
+      namespace "watcher"
+
+      HEADERS   = ["NAME", "TASK", "WATCHES", "DAEMON", "LAST RUN"].freeze
+      STOP_WAIT = 1.0
+
+      class << self
+        # The WATCHES column: the declared paths and, unless every kind of
+        # change counts, the kinds that do.
+        def describe(spec)
+          events = spec[:events].to_a.map(&:to_s)
+          kinds  = events.size == EVENTS.size ? "" : " [#{events.join(', ')}]"
+          "#{spec[:paths].join(' ')}#{kinds}"
+        end
+
+        # The LAST RUN column from an entry's record: never, still running,
+        # or its exit status with duration and finish time.
+        def last_run(entry)
+          return "never" unless entry
+          return "running (pid #{entry[:pid]})" unless entry.key?(:finished)
+
+          finished = Time.iso8601(entry[:finished]).strftime("%Y-%m-%d %H:%M:%S")
+          "#{entry[:status]} (#{format('%.1fs', entry[:seconds])}, #{finished})"
+        end
+      end
+
+      desc "tree", "Print a tree of the watcher subcommands", hide: true
+      # Redefined only to re-register tree as hidden in this namespace.
+      def tree = super # rubocop:disable Lint/UselessMethodDefinition
+
+      no_commands do
+        def watches = Watch.declarations
+
+        def watch_root = @watch_root ||= File.realpath((Asgard.find_task_file&.dirname || Pathname.pwd).to_s)
+
+        def watch_project = File.basename(watch_root)
+
+        def state = @state ||= State.new(project: watch_project, root: watch_root)
+
+        def declared_watches
+          abort "No watches declared. Add `watch :task, paths: \"lib\"` inside class Tasks in #{watch_root}/.loki." if watches.empty?
+
+          unknown = Daemon.unknown_tasks(watches, Tasks.all_commands.keys)
+          abort "watcher: no such task(s): #{unknown.join(', ')}" unless unknown.empty?
+
+          watches
+        end
+
+        def watch_direnv
+          return unless File.exist?(File.join(watch_root, ".envrc"))
+
+          Schedule.which("direnv", ENV.fetch("PATH", nil)) or
+            $stderr.puts "watcher: .envrc found but direnv is not on PATH; its variables will not be loaded"
+        end
+
+        def watch_asgard = Spawn.executable || abort("watcher: asgard is not on PATH")
+
+        def spawn_context
+          Spawn::Context.new(root: watch_root, log: state.log_path, base: Spawn.base_env, asgard: watch_asgard, direnv: watch_direnv)
+        end
+
+        def refuse_if_running
+          pid = state.running_pid
+          abort "watcher is already running for #{watch_project} (pid #{pid}); `asgard watcher stop` first." if pid
+        end
+
+        # `start` records the child's pid before the child reaches here, so a
+        # pidfile naming this very process is ours, not another daemon's.
+        def refuse_if_another_running
+          pid = state.running_pid
+          abort "watcher is already running for #{watch_project} (pid #{pid}); `asgard watcher stop` first." if pid && pid != Process.pid
+        end
+      end
+
+      # Thor reserves `run` as a method name, so the command is `daemon`
+      # with `run` as its usage and mapped name, as --version is _version.
+      desc "run", "Watch in the foreground until INT or TERM (what `start` runs detached)"
+      map "run" => :daemon
+      def daemon
+        specs = declared_watches
+        refuse_if_another_running
+        config = Daemon::Config.new(declarations: specs, root: watch_root, state:, context: spawn_context, tasks: Tasks.all_commands.keys)
+        Daemon.new(config).run
+      end
+
+      desc "start", "Start the watcher for this project in the background"
+      def start
+        specs = declared_watches
+        refuse_if_running
+        log = state.log_path
+        state.prepare.write_declarations(specs.values)
+        pid = Process.spawn(watch_asgard, "watcher", "run", chdir: watch_root, pgroup: true, out: [log, "a"], err: %i[child out])
+        Process.detach(pid)
+        state.write_pid(pid)
+        puts "started watcher for #{watch_project} (pid #{pid}); log: #{log}"
+      end
+
+      desc "stop", "Stop the watcher; a task already running finishes first"
+      def stop
+        pid = state.running_pid or abort("watcher is not running for #{watch_project}.")
+        Process.kill("TERM", pid)
+        while Reporter.alive?(pid)
+          running = state.running_entries.map { |entry| "#{entry[:entry]} (pid #{entry[:pid]})" }
+          puts "watcher: waiting for #{running.join(', ')}" unless running.empty?
+          sleep STOP_WAIT
+        end
+        state.clear
+        puts "stopped watcher for #{watch_project}"
+      end
+
+      no_commands do
+        # True when list should cover every project: asked for with --all, or
+        # there is no .loki here, so no single project to scope to.
+        def list_all? = options[:all] || Asgard.find_task_file.nil?
+
+        def no_watches_message
+          return "No watchers have been started on this machine." if list_all?
+
+          "No watches declared for #{watch_project}. Add `watch :task, paths: \"lib\"` inside class Tasks in #{watch_root}/.loki.\n" \
+            "Use `asgard watcher list --all` to see every project's watches."
+        end
+
+        # { title => rows } for every project, or { nil => rows } for this one; empty groups drop out.
+        def list_groups
+          groups = list_all? ? all_groups : { nil => Commands.project_rows(state, declared_records) }
+          groups.reject { |_, rows| rows.empty? }
+        end
+
+        def declared_records = watches.values.map { |spec| State.declaration_record(spec) }
+
+        # Every project with watcher state, titled "Project: slug (/root)". This
+        # project's rows come from its live declarations; the others' from what
+        # `start` recorded, since their .loki files are not loaded.
+        def all_groups
+          State.all.to_h do |slug, root|
+            other = State.new(project: slug, root:)
+            own   = Asgard.find_task_file && root == watch_root
+            ["Project: #{slug} (#{root})", Commands.project_rows(other, own ? declared_records : other.read_declarations)]
+          end
+        end
+      end
+
+      class << self
+        # One `list` row per declaration record, with the project's daemon
+        # state and each entry's last run.
+        def project_rows(project_state, records)
+          daemon  = project_state.running_pid ? "running" : "stopped"
+          entries = project_state.entries
+          records.map { |record| watch_row(record, daemon, entries[record[:name]]) }
+        end
+
+        def watch_row(record, daemon, entry)
+          { name: record[:name], command: "asgard #{record[:task]}", schedule: describe(record),
+            state: daemon, last_exit: last_run(entry) }
+        end
+      end
+
+      desc "list", "Show this project's watches, whether the watcher is running, and each entry's last run (--all: every project's)"
+      method_option :all, aliases: "-a", type: :boolean, desc: "List every project's watches, not just this one's"
+      def list
+        groups = list_groups
+        return puts(no_watches_message) if groups.empty?
+
+        puts groups.map { |title, rows| Schedule::Table.draw(rows, title:, headers: HEADERS) }.join("\n\n")
+        puts "\nLogs: #{State.base_dir}  (asgard watcher log)"
+      end
+
+      desc "preview", "Show the command and environment each watch would run, without running anything"
+      def preview
+        context = spawn_context
+        declared_watches.each_value { |spec| print_preview(spec, context) }
+      end
+
+      no_commands do
+        def print_preview(spec, context)
+          description = Spawn.description(spec, Changes.new, context)
+          puts "# #{spec[:name]}: #{Shellwords.join(description[:argv])}  (#{Commands.describe(spec)})"
+          description[:env].sort.each { |key, value| puts "#{key}=#{value}" }
+          puts
+        end
+      end
+
+      desc "log", "Print this project's watcher log to STDOUT"
+      method_option :follow, aliases: "-f", type: :boolean, desc: "Keep printing new output as it arrives (tail -f)"
+      def log
+        path = state.log_path
+        return $stderr.puts "#{watch_project} has no watcher log yet (#{path}); it is created on the first start." unless File.exist?(path)
+        return sh("tail -n +1 -f #{path.shellescape}", silent: true, exec: true) if options[:follow]
+
+        IO.copy_stream(path, $stdout)
+      end
+    end
+  end
+end
+# rubocop:enable Style/StderrPuts

data/lib/asgard/watch/daemon.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Asgard
+  module Watch
+    # `asgard watcher run`: the whole watcher in one foreground process.
+    # One Listen listener per declaration pushes batches onto the inbox;
+    # the dispatcher routes them to worker Ractors; the reporter writes the
+    # log and the entry records. A change to any .loki file re-execs the
+    # process so declarations are never stale. INT or TERM stops listening,
+    # drops triggers that have not started, waits for running tasks to
+    # exit, removes the pidfile and returns.
+    class Daemon
+      # What a run is made of: the normalized declarations, the real
+      # project root, the State, the Spawn::Context, and the names of the
+      # tasks the project defines.
+      Config = Data.define(:declarations, :root, :state, :context, :tasks)
+
+      LOKI_DEBOUNCE = 0.5
+
+      attr_reader :inbox, :listeners
+
+      # listen: is the Listen module (loaded only when nothing else is
+      # given) or a stand-in; exec: replaces the process on reload; out:
+      # is where shutdown progress goes.
+      def initialize(config, listen: Daemon.listen_module, exec: Kernel.method(:exec), out: $stdout)
+        @config     = config
+        @listen     = listen
+        @exec       = exec
+        @out        = out
+        @inbox      = Queue.new
+        @listeners  = []
+        @stopping   = false
+        @reporter   = nil
+        @dispatcher = nil
+      end
+
+      class << self
+        # Listen, loaded only when a daemon is actually built.
+        def listen_module
+          require "listen"
+          Listen
+        end
+
+        # The Listen options for one declaration.
+        def listen_options(spec)
+          { only: spec[:only], ignore: spec[:ignore], wait_for_delay: spec[:debounce], relative: true }.compact
+        end
+
+        # The tasks declared by watch but not defined by the project.
+        def unknown_tasks(declarations, tasks) = declarations.values.map { |spec| spec[:task] }.uniq - tasks
+      end
+
+      def run
+        check_tasks!
+        Dir.chdir(@config.root)
+        state = @config.state.prepare
+        start_pipeline(state)
+        @listeners = build_listeners + [loki_listener]
+        @listeners.each(&:start)
+        state.write_pid(Process.pid)
+        trap_signals
+        sleep 0.2 until @stopping
+        shutdown(state)
+      end
+
+      # Asks run to stop; the trap handler calls this.
+      def stop = @stopping = true
+
+      # Stops listening and replaces the process with a fresh `watcher run`
+      # so new declarations take effect. Running tasks, in their own
+      # process groups, carry on; the new daemon does not know about them.
+      def reload
+        @listeners.each(&:stop)
+        @exec.call(@config.context.asgard, "watcher", "run")
+      end
+
+      private
+
+      def check_tasks!
+        unknown = Daemon.unknown_tasks(@config.declarations, @config.tasks)
+        raise Error, "watch declares tasks this project does not define: #{unknown.join(', ')}" unless unknown.empty?
+      end
+
+      def start_pipeline(state)
+        reports     = RactorQueue.new(capacity: 1024)
+        @reporter   = Reporter.new(reports, log: state.log_path, state:)
+        @dispatcher = Dispatcher.new(@config.declarations, @config.context, reports:)
+        @reporter.start
+        @dispatcher.start(@inbox)
+      end
+
+      def build_listeners = @config.declarations.values.map { |spec| listener_for(spec) }
+
+      # One Listen listener whose callback pushes [entry name, batch] onto the inbox.
+      def listener_for(spec)
+        name = spec[:name]
+        @listen.to(*spec[:dirs], **Daemon.listen_options(spec)) do |modified, added, removed|
+          @inbox.push([name, { modified:, added:, removed: }])
+        end
+      end
+
+      def loki_listener
+        @listen.to(@config.root, only: /\.loki\z/, ignore: DEFAULT_IGNORES, wait_for_delay: LOKI_DEBOUNCE, relative: true) { reload }
+      end
+
+      def trap_signals
+        %w[INT TERM].each { |signal| trap(signal) { stop } }
+      end
+
+      def shutdown(state)
+        @listeners.each(&:stop)
+        @inbox.push(nil)
+        @dispatcher.workers.each_value do |worker|
+          queue = worker[:queue]
+          queue.try_pop until queue.empty?
+        end
+        @reporter.drain(out: @out)
+        state.clear
+        @out.puts "watcher: stopped"
+      end
+    end
+  end
+end

data/lib/asgard/watch/declaration.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module Asgard
+  # The platform-neutral half of the watcher: validates `watch` declarations
+  # and turns their paths into what Listen needs (directories to watch plus
+  # only:/ignore: filters). Everything here is pure, so each method can be
+  # tested on its own.
+  module Watch
+    # The kinds of change a declaration can react to. Listen calls the first
+    # one "modified"; that name is accepted as an alias.
+    EVENTS        = %i[changed added removed].freeze
+    EVENT_ALIASES = { modified: :changed }.freeze
+
+    # Output and scratch directories a task may write inside the project;
+    # always ignored so a task never retriggers itself. Matched against the
+    # path relative to the watched directory, at any depth.
+    DEFAULT_IGNORES = %w[.git coverage pkg tmp log node_modules].map { |dir| %r{(?:\A|/)#{Regexp.escape(dir)}/} }.freeze
+
+    GLOB_CHARS  = /[*?{]/
+    GLOB_TOKENS = %r!\*\*/|\*\*|\*|\?|\{[^}]*\}|\{|[^*?{]+!
+
+    module_function
+
+    # Validates a declaration and returns it as a plain Hash. paths: entries
+    # are directories, files or globs relative to the project root; the
+    # Hash carries the directories Listen watches and one only: Regexp (or
+    # nil) that stands for every pattern. events: picks which kinds of
+    # change trigger the task; as: names the entry. Every ArgumentError
+    # from the helpers below comes back prefixed with the task.
+    def normalize(task, paths:, only: nil, ignore: nil, events: :all, debounce: 0.5, env: {}, as: nil)
+      task = task.to_s
+      raise ArgumentError, "task name #{task.inspect} must be a single word" unless task.match?(/\A[\w:-]+\z/)
+
+      paths         = relative_paths(paths)
+      dirs, matched = watched(paths)
+      {
+        name:     entry_name(as || task),
+        task:,
+        paths:,
+        dirs:,
+        only:     combine_only(matched, regexps(:only, only)),
+        ignore:   [*regexps(:ignore, ignore), *DEFAULT_IGNORES],
+        events:   normalize_events(events),
+        debounce: non_negative_debounce(debounce),
+        env:      env.to_h { |key, value| [key.to_s, value.to_s] }
+      }
+    rescue ArgumentError => e
+      raise ArgumentError, "watch :#{task} #{e.message}"
+    end
+
+    # The entry name (as:, or the task), checked for the characters a file
+    # or label can carry.
+    def entry_name(name)
+      name = name.to_s
+      raise ArgumentError, "as: #{name.inspect} may only contain letters, digits, _ . -" unless name.match?(/\A[\w.-]+\z/)
+
+      name
+    end
+
+    # paths: as a non-empty Array of relative, non-empty Strings.
+    def relative_paths(paths)
+      paths = Array(paths).map(&:to_s)
+      raise ArgumentError, "needs at least one path" if paths.empty?
+
+      bad = paths.find { |path| path.empty? || File.absolute_path?(path) }
+      raise ArgumentError, "paths are relative to the project root (got #{bad.inspect})" if bad
+
+      paths
+    end
+
+    # [directories, patterns] for a declaration's paths. A bare directory
+    # takes everything beneath it, so it cannot share a declaration with a
+    # pattern or a file: Listen applies one only: filter to every directory
+    # it watches, and the pattern would silently filter the directory too.
+    def watched(paths)
+      splits   = paths.map { |path| split_glob(path) }
+      patterns = splits.filter_map(&:last)
+      if !patterns.empty? && patterns.size < splits.size
+        raise ArgumentError,
+              "mixes a bare directory with patterns or files, which would filter the directory too; " \
+              "declare them separately or write the directory as dir/**/*"
+      end
+
+      [splits.map(&:first).uniq, patterns]
+    end
+
+    # [directory, Regexp or nil] for one paths: entry.
+    #   "lib/**/*.rb"   => ["lib", /\A(?:.*\/)?[^\/]*\.rb\z/]
+    #   "lib/asgard.rb" => ["lib", /\Aasgard\.rb\z/]
+    #   "docs"          => ["docs", nil]
+    # The Regexp is matched against the path relative to the directory,
+    # which is how Listen applies only:. A plain path names a file when
+    # stat (File, or a stand-in in tests) finds one there or when it has
+    # an extension, so a file that does not exist yet can be watched.
+    def split_glob(path, stat: File)
+      segments = path.delete_suffix("/").split("/")
+      first    = segments.index { |segment| segment.match?(GLOB_CHARS) }
+      return [directory(segments[0...first]), glob_regexp(segments[first..].join("/"))] if first
+
+      *parents, last = segments
+      last = last.to_s
+      return [directory(segments), nil] unless stat.file?(path) || !File.extname(last).empty?
+
+      [directory(parents), /\A#{Regexp.escape(last)}\z/]
+    end
+
+    def directory(segments) = segments.empty? ? "." : segments.join("/")
+
+    # The Regexp a glob matches, shell-style: ** spans directories, * and ?
+    # stay within one, {a,b} is an alternative. Anything else is literal.
+    def glob_regexp(pattern)
+      body = pattern.scan(GLOB_TOKENS).map { |token| glob_token(token) }.join
+      /\A#{body}\z/
+    end
+
+    def glob_token(token)
+      case token
+      when "**/" then "(?:.*/)?"
+      when "**"  then ".*"
+      when "*"   then "[^/]*"
+      when "?"   then "[^/]"
+      when /\A\{(.*)\}\z/ then "(?:#{Regexp.last_match(1).split(',', -1).map { |alt| Regexp.escape(alt) }.join('|')})"
+      else Regexp.escape(token)
+      end
+    end
+
+    # One only: Regexp (or nil for no filter) from the patterns the paths
+    # produced and the declared only:. Within each group any may match;
+    # when both groups are present a path must satisfy one from each.
+    def combine_only(patterns, only)
+      any_pattern = patterns.empty? ? nil : Regexp.union(patterns)
+      any_only    = only.empty? ? nil : Regexp.union(only)
+      return any_pattern || any_only unless any_pattern && any_only
+
+      /(?=#{any_pattern})(?=.*?(?:#{any_only}))/
+    end
+
+    # only:/ignore: as an Array of Regexps.
+    def regexps(option, value)
+      list = Array(value)
+      bad  = list.find { |item| !item.is_a?(Regexp) }
+      raise ArgumentError, "#{option}: expects a Regexp or an Array of them (got #{bad.inspect})" if bad
+
+      list
+    end
+
+    # events: as a frozen Set of EVENTS. :all expands to every kind;
+    # :modified means :changed.
+    def normalize_events(value)
+      list    = Array(value).map { |event| event_name(event) }
+      unknown = list - EVENTS - [:all]
+      raise ArgumentError, "events: unknown #{unknown.first.inspect}; use :changed, :added, :removed or :all" unless unknown.empty?
+
+      list = EVENTS if list.include?(:all)
+      raise ArgumentError, "events: must name at least one of :changed, :added, :removed" if list.empty?
+
+      Set.new(list).freeze
+    end
+
+    def event_name(event)
+      name = event.to_sym
+      EVENT_ALIASES.fetch(name) { name }
+    end
+
+    def non_negative_debounce(debounce)
+      unless debounce.is_a?(Numeric) && !debounce.negative?
+        raise ArgumentError, "debounce: must be a number of seconds, zero or more (got #{debounce.inspect})"
+      end
+
+      debounce
+    end
+  end
+end

data/lib/asgard/watch/dispatcher.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "ractor_queue"
+
+module Asgard
+  module Watch
+    # Routes listener batches to worker queues. Built once at startup from
+    # the declarations: a dispatch table from listener id (the entry name)
+    # to its spec, and one worker per distinct task, so two declarations
+    # for the same task share a worker and never overlap. Nothing here is
+    # mutated after construction, and the loop never blocks on a worker.
+    class Dispatcher
+      # Triggers a busy task can have waiting. RactorQueue rounds this up.
+      QUEUE_CAPACITY = 256
+
+      attr_reader :dispatch, :workers
+
+      # start: makes a worker from (queue, reports); the default starts a
+      # real Ractor. clock: supplies the trigger timestamp.
+      def initialize(declarations, context, reports:, start: Worker.method(:start), clock: Time)
+        specs     = declarations.values
+        @context  = context
+        @reports  = reports
+        @clock    = clock
+        @dispatch = specs.to_h { |spec| [spec[:name], spec] }.freeze
+        @workers  = specs.map { |spec| spec[:task] }.uniq.to_h do |task|
+          queue = RactorQueue.new(capacity: QUEUE_CAPACITY)
+          [task, { queue:, ractor: start.call(queue, reports) }.freeze]
+        end.freeze
+      end
+
+      # Pops [listener id, batch] pairs from inbox until it pops nil.
+      def run(inbox)
+        while (id, batch = inbox.pop)
+          route(id, batch)
+        end
+      end
+
+      def start(inbox) = Thread.new { run(inbox) }
+
+      # One batch: drop the kinds the entry does not watch, build the frozen
+      # description, report the trigger, hand it to the task's worker. The
+      # description, or nil when nothing was left to run.
+      def route(id, batch)
+        spec    = @dispatch.fetch(id)
+        changes = Watch.filter_events(batch, spec[:events]) or return nil
+        task    = spec[:task]
+        description = Spawn.description(spec, changes, @context)
+        @reports.push(Ractor.make_shareable({ kind: :trigger, entry: spec[:name], task:, at: @clock.now.to_f, changes: changes.to_h }))
+        @workers.fetch(task)[:queue].push(description)
+        description
+      end
+    end
+  end
+end