glazed 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc8ac8baaf98756ff8b05fd712251274f27ec1c93bd02b980c528a5e8e059970
-  data.tar.gz: db6f2becb3b6d74ad1e44f8f8f385641e9732e92d54cf536130150988bac395b
+  metadata.gz: f09d16d28a4ecb996fa05ba53cc4af10d5cbe45b65c09f3830f88326a6e200c5
+  data.tar.gz: 7c40270ad31553fac8a681ba5369c1596cfaed4a8c09cf66036115def90bd4d9
 SHA512:
-  metadata.gz: 64eea926af805078a1e5e0a4653839e2c5ef5207f5515d1a8bfeb464f8ff2dbfda58ca6d25dc596c179ae8e9594f793f1548e10606b0bd2005ca087a735fc6c9
-  data.tar.gz: fe504897bf58461f509b0ca08e619661c52e04a9c75d61f4349d97d98679cb0f95ccdce73ad5216adfb7b1492f40f886bc14fc137c6ec11bf86be2982aacd41d
+  metadata.gz: d12cde4376d07ae82221202ebab2ec22a473b85dcdae0e2a5352d2f82235ed8e059a7a66fc7266d1d6d5e14eac5d68b2fdc05a34b22991aac18111d1620bd21e
+  data.tar.gz: b0e2f351f6ff580fd4b639162088ad4bfd3d947d8591805453129703ed227569d94c605124d43d760824d650c318450b6ab93766886c5e1fc2cd859b4eec1373

data/CHANGELOG.md

@@ -1,3 +1,22 @@
+## [0.2.0] - 2026-10-15
+
+### Breaking changes
+
+- Secrets are read through a `Glazed::SecretsResolver`, which `StepContext` holds and passes to the collector, dialect runs, the redactor and storages. `Glazed::Secret.new` takes the resolver, and `Secret.maybe` is replaced by `SecretsResolver#maybe`
+- Storages are built with `from_proto(settings, context:)`, where a `Glazed::StorageContext` carries the secrets resolver; plugin storages must accept it
+- The `shell` and `batch_shell` steps are renamed `command` and `batch_command` (`glazed.v1.CommandStep` and `BatchCommandStep`), as they also run programs without a shell
+
+### Enhancements
+
+- Redaction hides additional secrets given as secret references, as literal text or regular expressions and optionally split by a delimiter, in a `redact` step or in the top-level `redaction` shared by all of them
+- Storages: `subdirectory` for `git` and `github` places files in a directory of the repository instead of its root
+- `glazed signal --all`, and `all_nodes` and `workflows` on `glazed.v1.Signal`, signal every node of chosen workflows, for scheduled runs
+- `Glazed::Coordinator` and the `glazed.v1.CoordinatorTask` protocol let an external coordinator, such as AWS Step Functions with glazed-aws, drive the orchestrated workflows one step at a time
+- `SecretRef` gains `ssm`, an AWS Systems Manager parameter read by glazed-aws
+- `SecretRef` gains `command`, a value printed by a command
+- `command` and `batch_command` steps, `command` secrets and the `command` inventory take `exec`, a program and its arguments executed without a shell, in place of `run`
+- `sqlite` state backend: schema version 2 keeps the waiting coordinator execution. Version 1 databases are upgraded on first use, after which glazed 0.1.0 refuses them
+
 ## [0.1.0] - 2026-10-14
 
 Initial release.

data/lib/glazed/collector.rb

@@ -8,7 +8,7 @@ require 'glazed/cli_session'
 require 'glazed/dialect/run'
 require 'glazed/dialects'
 require 'glazed/proto'
-require 'glazed/secret'
+require 'glazed/secrets_resolver'
 require 'glazed/transports'
 
 module Glazed
@@ -25,8 +25,10 @@ module Glazed
     # @param transport [Transports::Base, nil] transport to use instead of building one from the node
     # @param timeout [Numeric] seconds to wait for each expected output
     # @param progress [Proc] receives a message when connecting and whenever waiting for the device
-    #: (node: Proto::V1::Node, ?transport: Transports::Base?, ?timeout: Numeric, ?progress: ^(String) -> void) -> void
-    def initialize(node:, transport: nil, timeout: CliSession::DEFAULT_TIMEOUT, progress: ->(_message) {})
+    # @param secrets [SecretsResolver] reads the node's password and secrets
+    #: (node: Proto::V1::Node, ?transport: Transports::Base?, ?timeout: Numeric, ?progress: ^(String) -> void, ?secrets: SecretsResolver) -> void
+    def initialize(node:, transport: nil, timeout: CliSession::DEFAULT_TIMEOUT, progress: ->(_message) {}, secrets: SecretsResolver.new)
+      @secrets = secrets #: SecretsResolver
       @node = node #: Proto::V1::Node
       @dialect = Dialects.find(node.dialect) #: singleton(Dialects::Base)
       @kind = (node.transport.empty? ? DEFAULT_TRANSPORT : node.transport) #: String
@@ -60,7 +62,7 @@ module Glazed
         timeout: @timeout,
         progress: @progress,
       )
-      run = Dialect::Run.new(cli: session, node:, dialect:)
+      run = Dialect::Run.new(cli: session, node:, dialect:, secrets: @secrets)
       @transport.pty_options = @config.pty_options
       @progress.call("connecting to #{@transport.host} over #{@kind}")
       @transport.open
@@ -93,7 +95,7 @@ module Glazed
       end
       if (password_prompt = @config.password_prompt)
         session.expect(password_prompt)
-        session.write("#{Secret.maybe(node.password)&.value}\n")
+        session.write("#{@secrets.maybe(node.password)&.value}\n")
       end
       session.expect(session.prompt)
     end
@@ -106,7 +108,9 @@ module Glazed
         host: node.host.empty? ? node.name : node.host,
         port: node.port.zero? ? nil : node.port,
         username: node.username,
-        password: Secret.maybe(node.password),
+        password: @secrets.maybe(node.password),
+        transport_options: node.transport_options,
+        secrets: @secrets,
       )
     end
   end

data/lib/glazed/command/base.rb

@@ -6,13 +6,12 @@
 require 'json'
 require 'dry/cli'
 require 'glazed'
+require 'glazed/config'
 require 'glazed/must'
 require 'glazed/proto'
-require 'glazed/proto_json'
 require 'glazed/runner'
 require 'glazed/state_backends'
 require 'glazed/step_context'
-require 'glazed/validation'
 
 module Glazed
   module Command
@@ -91,8 +90,7 @@ module Glazed
       #: (Proto::V1::Config config) -> Integer
       private def default_jobs(config) = config.jobs.zero? ? DEFAULT_JOBS : config.jobs
 
-      # Reads the config, first requiring the features its `requires` lists so
-      # plugin settings types are known when it is decoded.
+      # Reads the config with {Glazed::Config.load}.
       #
       # @param path [String] config file
       # @return [Proto::V1::Config] the config
@@ -100,20 +98,7 @@ module Glazed
       # @raise [InvalidMessage] when the config breaks the rules of its schema
       # @raise [LoadError] when a required feature is missing
       #: (String path) -> Proto::V1::Config
-      private def load_config(path)
-        json = ::File.read(path)
-        document = JSON.parse(json) #: untyped
-        requires = document.is_a?(Hash) ? document.fetch('requires', []) : []
-        unless requires.is_a?(Array) && requires.all?(String)
-          raise Glazed::Error, "#{path}: requires must be a list of strings"
-        end
-
-        requires.each { require it }
-        ProtoJson.load(Proto::V1::Config, json).tap { Validation.validate!(it, origin: path) }
-      rescue Google::Protobuf::ParseError, JSON::ParserError => e
-        hint = e.message.include?('Type was not found') ? '; list the gem providing that plugin type in requires' : ''
-        raise Glazed::Error, "#{path}: #{e.message}#{hint}"
-      end
+      private def load_config(path) = Glazed::Config.load(path)
 
       # @param config [Proto::V1::Config] the config
       # @param name [String, nil] requested workflow

data/lib/glazed/command/orchestrate.rb

@@ -38,7 +38,7 @@ module Glazed
         settings = load_config(config)
         orchestration = orchestrator_settings(settings, config)
         listener = json_listener
-        context = StepContext.from_proto(settings.storages, listener:)
+        context = StepContext.from_proto(settings.storages, redaction: settings.redaction, listener:)
         workflows = orchestration.workflows.keys.to_h { [it, Workflow.from_proto(select_workflow(settings, it), context:)] }
         backend = state_backend(orchestration, context)
         orchestrator = Orchestrator.new(

data/lib/glazed/command/run.rb

@@ -37,7 +37,7 @@ module Glazed
 
         settings = load_config(config)
         listener = json_listener
-        context = StepContext.from_proto(settings.storages, listener:)
+        context = StepContext.from_proto(settings.storages, redaction: settings.redaction, listener:)
         steps = Workflow.from_proto(select_workflow(settings, workflow), context:)
         nodes = select_nodes(Sources.nodes(settings.inventory.to_a), only || [])
 

data/lib/glazed/command/send_signal.rb

@@ -6,8 +6,8 @@
 require 'time'
 require 'google/protobuf'
 require 'glazed/command/base'
+require 'glazed/coordinator'
 require 'glazed/must'
-require 'glazed/orchestrator'
 require 'glazed/proto'
 require 'glazed/sources'
 require 'glazed/state_backends'
@@ -23,42 +23,50 @@ module Glazed
     # each node is due.
     class SendSignal < Base
       desc 'Make nodes due soon for glazed orchestrate'
-      argument :nodes, type: :array, required: true, desc: 'Names of the nodes'
+      argument :nodes, type: :array, required: false, desc: 'Names of the nodes'
       option :config, aliases: ['-c'], desc: 'Config file, ProtoJSON of glazed.v1.Config; $GLAZED_CONFIG_FILE when omitted'
       option :workflow, aliases: ['-w'], type: :array, desc: 'Signal only these orchestrated workflows, comma-separated'
+      option :all, type: :boolean, default: false, desc: 'Signal every node in the inventory instead of the named ones'
       option :source, default: 'manual', desc: 'What sent the signal, recorded as the reason the node is due'
       option :now, type: :boolean, default: false, desc: 'Make the nodes due now, without the debounce delay'
 
       # Records the signals.
       #
-      # @param nodes [Array<String>] node names
+      # @param nodes [Array<String>, nil] node names; none with all
       # @param config [String, nil] path of the config file; {Base::CONFIG_FILE_ENV} when nil
       # @param workflow [Array<String>, nil] workflows to signal; every orchestrated one when nil
+      # @param all [Boolean] whether to signal every node in the inventory
       # @param source [String] what sent the signal
       # @param now [Boolean] whether to skip the debounce delay
       # @param _options [Hash] other options dry-cli passes, unused
       # @return [void]
       # @raise [Glazed::Error, Google::Protobuf::ParseError] when the config is invalid, a node is unknown, or the state backend fails
-      #: (nodes: Array[String], ?config: String?, ?workflow: Array[String]?, ?source: String, ?now: bool, **untyped _options) -> void
-      def call(nodes:, config: nil, workflow: nil, source: 'manual', now: false, **_options)
+      #: (?nodes: Array[String]?, ?config: String?, ?workflow: Array[String]?, ?all: bool, ?source: String, ?now: bool, **untyped _options) -> void
+      def call(nodes: nil, config: nil, workflow: nil, all: false, source: 'manual', now: false, **_options)
         config = config_path(config, 'signal')
+        nodes ||= []
+        if all != nodes.empty?
+          err.puts 'glazed signal: name nodes, or give --all'
+          exit 1
+        end
 
         settings = load_config(config)
         orchestration = orchestrator_settings(settings, config)
         workflows = select_orchestrated(orchestration, workflow)
-        select_nodes(Sources.nodes(settings.inventory.to_a), nodes)
+        inventory = Sources.nodes(settings.inventory.to_a).map(&:name)
+        select_nodes(inventory.map { Proto::V1::Node.new(name: it) }, nodes)
         context = StepContext.from_proto(settings.storages, listener: json_listener)
         backend = state_backend(orchestration, context)
         at = Time.now
-        signals = nodes.map do |node|
-          Proto::V1::Signal.new(node:, source:, received_at: Google::Protobuf::Timestamp.from_time(at), immediate: now).tap { Validation.validate!(it) }
+        received_at = Google::Protobuf::Timestamp.from_time(at)
+        signals = (all ? [nil] : nodes.uniq).map do |node|
+          Proto::V1::Signal.new(node: node || '', all_nodes: all, source:, received_at:, immediate: now, workflows:).tap { Validation.validate!(it) }
         end
+        records = Coordinator.new(settings: orchestration, backend:, clock: -> { at }).signal(signals, nodes: inventory)
         workflows.each do |name|
-          debounce = orchestration.workflows[name]&.debounce
-          records = Orchestrator.signal(backend:, workflow: name, signals:, debounce:, now: at)
-          nodes.uniq.each do |node|
-            due_at = Must.because(records.fetch(node).due_at) { 'validation requires due_at' }
-            out.puts "#{node} #{name} due at #{due_at.to_time.utc.iso8601}"
+          records.fetch(name, {}).each_value do |record|
+            due_at = Must.because(record.due_at) { 'validation requires due_at' }
+            out.puts "#{record.node} #{name} due at #{due_at.to_time.utc.iso8601}"
           end
         end
       ensure

data/lib/glazed/config.rb

@@ -0,0 +1,50 @@
+# typed: strict
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: Apache-2.0
+
+require 'json'
+require 'google/protobuf'
+require 'glazed'
+require 'glazed/proto'
+require 'glazed/proto_json'
+require 'glazed/validation'
+
+module Glazed
+  # Reads glazed configs ({Proto::V1::Config}).
+  module Config
+    # Reads a config file with {.parse}.
+    #
+    # @param path [String] config file
+    # @return [Proto::V1::Config] the config
+    # @raise [Glazed::Error] when `requires` is malformed, or the config does not decode
+    # @raise [InvalidMessage] when the config breaks the rules of its schema
+    # @raise [LoadError] when a required feature is missing
+    #: (String path) -> Proto::V1::Config
+    def self.load(path) = parse(::File.read(path), origin: path)
+
+    # Decodes a config, first requiring the features its `requires` lists so
+    # plugin settings types are known when it is decoded.
+    #
+    # @param json [String] ProtoJSON of {Proto::V1::Config}
+    # @param origin [String] where the config comes from, for error messages
+    # @return [Proto::V1::Config] the config
+    # @raise [Glazed::Error] when `requires` is malformed, or the config does not decode
+    # @raise [InvalidMessage] when the config breaks the rules of its schema
+    # @raise [LoadError] when a required feature is missing
+    #: (String json, origin: String) -> Proto::V1::Config
+    def self.parse(json, origin:)
+      document = JSON.parse(json) #: untyped
+      requires = document.is_a?(Hash) ? document.fetch('requires', []) : []
+      unless requires.is_a?(Array) && requires.all?(String)
+        raise Glazed::Error, "#{origin}: requires must be a list of strings"
+      end
+
+      requires.each { require it }
+      ProtoJson.load(Proto::V1::Config, json).tap { Validation.validate!(it, origin:) }
+    rescue Google::Protobuf::ParseError, JSON::ParserError => e
+      hint = e.message.include?('Type was not found') ? '; list the gem providing that plugin type in requires' : ''
+      raise Glazed::Error, "#{origin}: #{e.message}#{hint}"
+    end
+  end
+end

data/lib/glazed/coordinator/task_runner.rb

@@ -0,0 +1,189 @@
+# typed: strict
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: Apache-2.0
+
+require 'glazed'
+require 'glazed/coordinator'
+require 'glazed/must'
+require 'glazed/proto'
+require 'glazed/runner'
+require 'glazed/steps'
+require 'glazed/workflow'
+
+module Glazed
+  class Coordinator
+    # Performs {Proto::V1::CoordinatorTask}s for an external coordinator, such
+    # as AWS Step Functions, which runs each step of a workflow as its own
+    # call and passes the protobuf results between them. Node failures are
+    # returned as {Proto::V1::StepFailure}s rather than raised, so the
+    # coordinator carries them to the end of the batch.
+    #
+    # @example
+    #   runner = Glazed::Coordinator::TaskRunner.new(coordinator:, workflows:, inventory: -> { Glazed::Sources.nodes(config.inventory.to_a) })
+    #   batches = runner.perform(Glazed::Proto::V1::CoordinatorTask.new(prepare: {}))
+    class TaskRunner
+      # Cycles a coordinator execution runs when the task sets none.
+      DEFAULT_MAX_CYCLES = 20 #: Integer
+
+      #: type result = Proto::V1::Armed | Proto::V1::PreparedBatches | Proto::V1::NodeOutcome | Proto::V1::Batch
+
+      # @param coordinator [Coordinator] changes the node schedules
+      # @param workflows [Hash{String => Workflow}] the orchestrated workflows, by name
+      # @param inventory [Proc] loads the current nodes
+      # @param listener [Proc] receives events of the tasks and steps
+      # @raise [ArgumentError] when the workflows differ from those the coordinator orchestrates
+      #: (coordinator: Coordinator, workflows: Hash[String, Workflow], inventory: Orchestrator::inventory, ?listener: Runner::listener) -> void
+      def initialize(coordinator:, workflows:, inventory:, listener: ->(_event) {})
+        unless workflows.keys.sort == coordinator.workflows.sort
+          raise ArgumentError, "workflows #{workflows.keys.sort} differ from the orchestrated #{coordinator.workflows.sort}"
+        end
+
+        @coordinator = coordinator #: Coordinator
+        @workflows = workflows #: Hash[String, Workflow]
+        @inventory = inventory #: Orchestrator::inventory
+        @listener = listener #: Runner::listener
+      end
+
+      # @param task [Proto::V1::CoordinatorTask] the task
+      # @return [Proto::V1::Armed, Proto::V1::PreparedBatches, Proto::V1::NodeOutcome, Proto::V1::Batch] its result
+      # @raise [InvalidMessage] when the task breaks the rules of its schema
+      # @raise [ArgumentError] when the task names an unknown workflow or step
+      # @raise [Glazed::Error] when the inventory or the state backend fails
+      #: (Proto::V1::CoordinatorTask task) -> TaskRunner::result
+      def perform(task)
+        Validation.validate!(task)
+        if (check = task.check) then check(check)
+        elsif task.prepare then prepare
+        elsif (node_step = task.node_step) then node_step(node_step)
+        elsif (batch_step = task.batch_step) then batch_step(batch_step)
+        else complete(Must.because(task.complete) { 'validation requires a task' })
+        end
+      end
+
+      # @param task [Proto::V1::CheckTask] the task
+      # @return [Proto::V1::Armed] when to wake up, if at all
+      #: (Proto::V1::CheckTask task) -> Proto::V1::Armed
+      private def check(task)
+        nodes = load_inventory.keys
+        @coordinator.sync_inventory(nodes)
+        @coordinator.signal(task.signals.to_a, nodes:) unless task.signals.empty?
+        wake = @coordinator.arm(
+          token: task.token, cycle: task.cycle, max_cycles: task.max_cycles.zero? ? DEFAULT_MAX_CYCLES : task.max_cycles,
+          grace: task.grace_seconds.zero? ? nil : task.grace_seconds,
+        )
+        Proto::V1::Armed.new(wait_until: wake && Google::Protobuf::Timestamp.from_time(wake))
+      end
+
+      # @return [Proto::V1::PreparedBatches] a batch of the due nodes of each workflow
+      #: () -> Proto::V1::PreparedBatches
+      private def prepare
+        inventory = load_inventory
+        @coordinator.sync_inventory(inventory.keys)
+        batches = @workflows.keys.to_h do |workflow|
+          owner, names = @coordinator.claim(workflow)
+          nodes = names.filter_map { inventory[it] }.map { Proto::V1::NodeOutcome.new(state: Proto::V1::NodeState.new(node: it)) }
+          notify(level: 'info', workflow:, message: 'batch started', nodes: nodes.map { it.state&.node&.name.to_s }) unless nodes.empty?
+          [workflow, Proto::V1::Batch.new(workflow:, owner:, nodes:)]
+        end
+        Proto::V1::PreparedBatches.new(batches:)
+      end
+
+      # @param task [Proto::V1::NodeStepTask] the task
+      # @return [Proto::V1::NodeOutcome] the node's outcome after the step
+      # @raise [ArgumentError] when the step is unknown or not a per-node step
+      #: (Proto::V1::NodeStepTask task) -> Proto::V1::NodeOutcome
+      private def node_step(task)
+        step = step(task.workflow, task.step, Steps::NodeStep)
+        outcome = Must.because(task.outcome) { 'validation requires outcome' }
+        return outcome if outcome.failure
+
+        state = Must.because(outcome.state) { 'validation requires state' }
+        node = state.node&.name.to_s
+        begin
+          after = step.call(state)
+        rescue StandardError => e
+          # One unreachable or misbehaving device must not stop the others.
+          notify(level: 'error', step: step.name, node:, error: e.class.name, message: e.message)
+          return Proto::V1::NodeOutcome.new(state:, failure: Proto::V1::StepFailure.new(step: step.name, error: e.message))
+        end
+        notify(level: 'info', step: step.name, node:, changed: changed?(after, step), message: 'done')
+        Proto::V1::NodeOutcome.new(state: after)
+      end
+
+      # @param task [Proto::V1::BatchStepTask] the task
+      # @return [Proto::V1::Batch] the batch after the step
+      # @raise [ArgumentError] when the step is unknown or not a batch step
+      #: (Proto::V1::BatchStepTask task) -> Proto::V1::Batch
+      private def batch_step(task)
+        batch = Must.because(task.batch) { 'validation requires batch' }
+        step = step(batch.workflow, task.step, Steps::BatchStep)
+        return batch unless batch.error.empty?
+
+        passing = batch.nodes.filter_map { it.state unless it.failure }
+        begin
+          after = step.call(Proto::V1::BatchState.new(nodes: passing)).nodes.to_h { [it.node&.name, it] }
+        rescue StandardError => e
+          notify(level: 'error', workflow: batch.workflow, step: step.name, error: e.class.name, message: e.message)
+          return batch.dup.tap { it.error = "#{step.name}: #{e.message}" }
+        end
+        notify(level: 'info', workflow: batch.workflow, step: step.name, nodes: after.size, message: 'done')
+        nodes = batch.nodes.map do |outcome|
+          state = after[outcome.state&.node&.name]
+          outcome.failure || state.nil? ? outcome : Proto::V1::NodeOutcome.new(state:)
+        end
+        Proto::V1::Batch.new(workflow: batch.workflow, owner: batch.owner, nodes:)
+      end
+
+      # @param task [Proto::V1::CompleteTask] the task
+      # @return [Proto::V1::Batch] the batch, unchanged
+      #: (Proto::V1::CompleteTask task) -> Proto::V1::Batch
+      private def complete(task)
+        batch = Must.because(task.batch) { 'validation requires batch' }
+        names = batch.nodes.map { it.state&.node&.name.to_s }
+        errors = {} #: Hash[String, String]
+        batch.nodes.each do |outcome|
+          failure = outcome.failure
+          error = failure ? "#{failure.step}: #{failure.error}" : batch.error
+          errors[outcome.state&.node&.name.to_s] = error unless error.empty?
+        end
+        @coordinator.complete(batch.workflow, owner: batch.owner, names:, errors:)
+        notify(level: 'info', workflow: batch.workflow, message: 'batch finished', nodes: names.size, failed: errors.size)
+        batch
+      end
+
+      # @return [Hash{String => Proto::V1::Node}] every node in the inventory, by name
+      #: () -> Hash[String, Proto::V1::Node]
+      private def load_inventory
+        nodes = @inventory.call.to_h { [it.name, it] }
+        notify(level: 'info', message: 'inventory loaded', nodes: nodes.size)
+        nodes
+      end
+
+      # @param workflow [String] workflow name
+      # @param name [String] step name
+      # @param kind [Class] {Steps::NodeStep} or {Steps::BatchStep}
+      # @return [Steps::Base] the step
+      # @raise [ArgumentError] when the step is unknown or of another kind
+      #: [S < Steps::Base] (String workflow, String name, Class[S] kind) -> S
+      private def step(workflow, name, kind)
+        steps = @workflows.fetch(workflow) { raise ArgumentError, "workflow #{workflow.inspect} is not orchestrated" }.steps
+        found = steps.find { it.name == name } or raise ArgumentError, "workflow #{workflow.inspect} has no step #{name.inspect}"
+        raise ArgumentError, "#{workflow}: #{name} is not a #{kind.name}" unless found.is_a?(kind)
+
+        found
+      end
+
+      # @param state [Proto::V1::NodeState] state after the step
+      # @param step [Steps::Base] the step
+      # @return [Boolean] whether any artifact the step produced changed stored content
+      #: (Proto::V1::NodeState state, Steps::Base step) -> bool
+      private def changed?(state, step) = step.outputs.any? { state.artifacts[it]&.changed }
+
+      # @param event [Hash{Symbol => String, Integer, Boolean, Array<String>, nil}] event fields
+      # @return [void]
+      #: (**Runner::event_value event) -> void
+      private def notify(**event) = @listener.call(event)
+    end
+  end
+end