agentboard 0.2.0

data/lib/agentboard/providers/fake_agent_script.rb

@@ -0,0 +1,47 @@
+# Deterministic fake coding agent used by AgentBoard's Fake provider.
+# Reads the prompt from stdin, emits JSONL on stdout and edits the current directory.
+require "json"
+require "fileutils"
+
+$stdout.sync = true
+args = ARGV.each_slice(2).to_h
+scenario = args.fetch("--scenario", "success")
+prompt = $stdin.read.to_s
+ticket = ENV.fetch("AGENTBOARD_TICKET", "UNKNOWN")
+
+emit = ->(h) { puts(JSON.generate(h)) }
+trap("TERM") { emit.call(type: "message", text: "received SIGTERM, stopping"); exit 143 }
+
+emit.call(type: "session", session_id: args["--session"] || "fake-#{Process.pid}", model: "fake-1")
+emit.call(type: "message", text: "Read #{prompt.bytesize} bytes of context for #{ticket}.")
+
+case scenario
+when "malformed"
+  puts "this is not json {"
+  emit.call(type: "mystery", foo: 1)
+when "secret"
+  emit.call(type: "message", text: "Found key sk-ant-api03-ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 in env")
+when "permission"
+  emit.call(type: "permission", tool: "Bash", reason: "wants to run rm -rf tmp/")
+when "env"
+  # Simulates an agent that obeys a prompt-injected instruction to dump its environment.
+  ENV.sort.each { |k, v| emit.call(type: "message", text: "#{k}=#{v}") }
+when "resume"
+  emit.call(type: "message", text: "Resumed session #{args["--session"]}: #{prompt.strip[0, 80]}")
+when "slow"
+  20.times { |i| emit.call(type: "message", text: "working… #{i}"); sleep 0.5 }
+end
+
+unless scenario == "noop"
+  emit.call(type: "tool_start", tool: "Edit", target: "AGENTBOARD_NOTES.md")
+  File.open("AGENTBOARD_NOTES.md", "a") { |f| f.puts("- #{ticket}: change by fake agent (#{scenario})") }
+  emit.call(type: "tool_end", tool: "Edit", target: "AGENTBOARD_NOTES.md", ok: true)
+end
+emit.call(type: "usage", input_tokens: prompt.bytesize / 4, output_tokens: 42)
+
+if scenario == "fail"
+  emit.call(type: "result", ok: false, summary: "Could not complete the task")
+  exit 1
+end
+emit.call(type: "result", ok: true, summary: "Implemented #{ticket} (fake)")
+exit 0

data/lib/agentboard/providers/generic_cli.rb

@@ -0,0 +1,35 @@
+module Agentboard
+  module Providers
+    # Placeholder adapters for P2 providers (Gemini CLI, OpenCode, Copilot). They detect the
+    # binary and report MCP-only capability; active execution is unavailable until a
+    # fixture-backed adapter is written. This keeps the UI honest about support levels.
+    class GenericCli < Base
+      class << self
+        attr_reader :provider_key, :binary_name, :display
+
+        def for(key:, binary:, display:)
+          Class.new(self) do
+            @provider_key = key
+            @binary_name = binary
+            @display = display
+          end
+        end
+
+        def key = provider_key.to_sym
+        def display_name = display
+        def binary = binary_name
+      end
+
+      def probe(environment: ENV)
+        bin = which(self.class.binary)
+        version = bin && run_version([ bin, "--version" ]).to_s[/\d+\.\d+(?:\.\d+)?/]
+        ProbeResult.new(provider: key, installed: !bin.nil?, version: version, authenticated: nil,
+                        supported_capabilities: bin ? %i[mcp] : [], validation: bin ? "detected (P2, MCP only)" : "not installed",
+                        diagnostics: [ "#{display_name}: only MCP configuration is supported in this release." ])
+      end
+
+      def launch_spec(**) = raise(UnsupportedCapability.new(:active_execution, provider: key))
+      def parse_event(raw_event:) = [ NormalizedEvent.build("agent.execution.output", { "text" => raw_event.to_s[0, 4000] }) ]
+    end
+  end
+end

data/lib/agentboard/providers/registry.rb

@@ -0,0 +1,31 @@
+module Agentboard
+  module Providers
+    class Registry
+      REQUIRED_METHODS = %i[probe parse_event launch_spec].freeze
+
+      def initialize
+        @adapters = {}
+      end
+
+      def register(key, adapter)
+        key = key.to_s
+        raise ArgumentError, "provider key must match /\\A[a-z][a-z0-9_]*\\z/" unless key.match?(/\A[a-z][a-z0-9_]*\z/)
+        missing = REQUIRED_METHODS.reject { |m| adapter.method_defined?(m) }
+        raise ArgumentError, "#{adapter} must implement #{missing.join(", ")}" if missing.any?
+
+        @adapters[key] = adapter
+      end
+
+      def keys = @adapters.keys
+      def registered?(key) = @adapters.key?(key.to_s)
+
+      def adapter_class(key)
+        @adapters.fetch(key.to_s) { raise Error.not_found("Unknown provider #{key}") }
+      end
+
+      def fetch(key, settings: nil) = adapter_class(key).new(settings: settings)
+      def each(&) = @adapters.each_key.map { |k| fetch(k) }.each(&)
+      def all = @adapters.keys.map { |k| fetch(k) }
+    end
+  end
+end

data/lib/agentboard/providers/types.rb

@@ -0,0 +1,32 @@
+module Agentboard
+  module Providers
+    CAPABILITIES = %i[mcp passive_hooks active_execution structured_events streaming cancellation session_resume permission_requests].freeze
+
+    # Typed results (spec §26.1). Handles never carry provider secrets.
+    ProbeResult = Struct.new(:provider, :installed, :version, :authenticated, :supported_capabilities, :validation, :diagnostics, keyword_init: true) do
+      def supports?(cap) = Array(supported_capabilities).include?(cap.to_sym)
+
+      def to_h
+        { provider: provider, installed: installed, version: version, authenticated: authenticated,
+          supported_capabilities: Array(supported_capabilities).map(&:to_s), validation: validation, diagnostics: diagnostics }
+      end
+    end
+
+    # What the supervisor needs to spawn a provider process safely.
+    # mounts: extra host paths mounted read-only when the agent runs in a container.
+    # credential_aliases: { "NAME_IN_CONTAINER" => "HOST_VARIABLE" } — forwarded by name only.
+    LaunchSpec = Struct.new(:argv, :env, :stdin_data, :chdir, :passthrough_env, :mounts, :credential_aliases, keyword_init: true)
+
+    # Normalized event produced by `parse_event`.
+    NormalizedEvent = Struct.new(:type, :payload, :external_session_id, :usage, :terminal, :status, :provenance, keyword_init: true) do
+      def self.build(type, payload = {}, **opts)
+        new(type: type, payload: payload, provenance: "provider_reported", terminal: false, **opts)
+      end
+    end
+
+    Usage = Struct.new(:input_tokens, :output_tokens, :reported_cost, :currency, :metering_kind, keyword_init: true)
+
+    # Passive setup outcome: exact changes for display and the reversal manifest.
+    SetupResult = Struct.new(:provider, :changes, :manifest, :backups, :warnings, keyword_init: true)
+  end
+end

data/lib/agentboard/providers.rb

@@ -0,0 +1,26 @@
+require "agentboard/subprocess"
+require "agentboard/providers/types"
+require "agentboard/providers/base"
+require "agentboard/providers/registry"
+require "agentboard/providers/config_editor"
+require "agentboard/providers/fake"
+require "agentboard/providers/claude_code"
+require "agentboard/providers/codex"
+require "agentboard/providers/cursor"
+require "agentboard/providers/generic_cli"
+
+module Agentboard
+  module Providers
+    def self.registry
+      @registry ||= Registry.new.tap do |r|
+        r.register(:fake, Fake)
+        r.register(:claude, ClaudeCode)
+        r.register(:codex, Codex)
+        r.register(:cursor, Cursor)
+        r.register(:gemini, GenericCli.for(key: "gemini", binary: "gemini", display: "Gemini CLI"))
+        r.register(:opencode, GenericCli.for(key: "opencode", binary: "opencode", display: "OpenCode"))
+        r.register(:copilot, GenericCli.for(key: "copilot", binary: "copilot", display: "GitHub Copilot CLI"))
+      end
+    end
+  end
+end

data/lib/agentboard/rails_introspection.rb

@@ -0,0 +1,49 @@
+module Agentboard
+  # Static Rails metadata via Prism — never boots or executes repository code (spec §10).
+  module RailsIntrospection
+    HTTP_VERBS = %w[get post put patch delete match].freeze
+
+    module_function
+
+    # Returns [{ verb:, path:, kind: }] from config/routes.rb.
+    def routes(root)
+      path = File.join(root.to_s, "config", "routes.rb")
+      return [] unless File.file?(path)
+
+      require "prism"
+      found = []
+      walk = ->(node) do
+        if node.is_a?(Prism::CallNode) && node.receiver.nil?
+          name = node.name.to_s
+          first = node.arguments&.arguments&.first
+          label = case first
+                  when Prism::SymbolNode then first.unescaped
+                  when Prism::StringNode then first.unescaped
+                  when Prism::KeywordHashNode then first.elements.first&.key&.slice
+                  end
+          if %w[resources resource namespace scope].include?(name) && label
+            found << { verb: name, path: label.to_s, kind: "resource" }
+          elsif HTTP_VERBS.include?(name) && label
+            found << { verb: name.upcase, path: label.to_s, kind: "route" }
+          elsif name == "root"
+            found << { verb: "GET", path: "/", kind: "root" }
+          end
+        end
+        node.compact_child_nodes.each { |c| walk.(c) }
+      end
+      walk.(Prism.parse_file(path).value)
+      found.first(300)
+    rescue StandardError, LoadError
+      []
+    end
+
+    # Table names created by migrations (static scan).
+    def migration_tables(root)
+      Dir[File.join(root.to_s, "db", "migrate", "*.rb")].sort.last(200).flat_map do |f|
+        File.read(f, 200_000).scan(/create_table\s+[:"']([a-z0-9_]+)/).flatten
+      end.uniq
+    rescue StandardError
+      []
+    end
+  end
+end

data/lib/agentboard/redactor.rb

@@ -0,0 +1,62 @@
+module Agentboard
+  # Redacts secrets from logs, hook payloads, event fields and exports (spec §14, AT-13).
+  # Patterns are intentionally conservative; projects can add their own via configuration.
+  module Redactor
+    MASK = "[REDACTED]".freeze
+
+    DEFAULT_PATTERNS = [
+      /\bsk-ant-[A-Za-z0-9_\-]{16,}/,                        # Anthropic
+      /\bsk-(?:proj-)?[A-Za-z0-9_\-]{20,}/,                  # OpenAI
+      /\bgh[pousr]_[A-Za-z0-9]{30,}/,                        # GitHub tokens
+      /\bgithub_pat_[A-Za-z0-9_]{30,}/,
+      /\bxox[abposr]-[A-Za-z0-9\-]{10,}/,                    # Slack
+      /\bAKIA[0-9A-Z]{16}\b/,                                # AWS access key id
+      /\bAIza[0-9A-Za-z_\-]{35}\b/,                          # Google API key
+      /\beyJ[A-Za-z0-9_\-]{10,}\.[A-Za-z0-9_\-]{10,}\.[A-Za-z0-9_\-]{10,}/, # JWT
+      /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/,
+      /(?<=:\/\/)[^\/\s:@]+:[^\/\s@]+(?=@)/                 # credentials in URLs
+    ].freeze
+
+    # key=value / "key": "value" assignments for sensitive-looking keys
+    ASSIGNMENT = /((?:api[_-]?key|secret|token|password|passwd|authorization|bearer|private[_-]?key|access[_-]?key|lease_token)["']?\s*[:=]\s*["']?)([^\s"',;}]{6,})/i
+
+    SENSITIVE_KEYS = /\A(?:.*(?:password|passwd|secret|token|api[_-]?key|authorization|cookie|credential|private[_-]?key).*)\z/i
+
+    module_function
+
+    def patterns
+      DEFAULT_PATTERNS + Array(Agentboard.config.redaction_patterns)
+    end
+
+    # Returns [redacted_string, count_of_redactions]
+    def redact_with_count(text)
+      return [ text, 0 ] unless text.is_a?(String)
+
+      count = 0
+      out = text.dup
+      patterns.each do |re|
+        out = out.gsub(re) { count += 1; MASK }
+      end
+      out = out.gsub(ASSIGNMENT) { count += 1; "#{$1}#{MASK}" }
+      [ out, count ]
+    end
+
+    def redact(text) = redact_with_count(text).first
+
+    def secret?(text) = redact_with_count(text).last.positive?
+
+    # Deep redaction of hashes/arrays: sensitive keys are masked entirely,
+    # strings are pattern-scanned.
+    def redact_value(value)
+      case value
+      when Hash
+        value.each_with_object({}) do |(k, v), h|
+          h[k] = (k.to_s.match?(SENSITIVE_KEYS) && !v.is_a?(Hash) && !v.is_a?(Array) && !v.nil?) ? MASK : redact_value(v)
+        end
+      when Array then value.map { |v| redact_value(v) }
+      when String then redact(value)
+      else value
+      end
+    end
+  end
+end

data/lib/agentboard/result.rb

@@ -0,0 +1,46 @@
+module Agentboard
+  # Command result envelope (spec §24.3):
+  #   { ok: true,  data: {...}, correlation_id: "c-123" }
+  #   { ok: false, error: { code:, message:, retryable:, details: }, correlation_id: "c-123" }
+  class Result
+    attr_reader :data, :error, :correlation_id
+
+    def self.success(data = {}, correlation_id: Ids.correlation) = new(data: data, correlation_id: correlation_id)
+    def self.failure(error, correlation_id: Ids.correlation) = new(error: error, correlation_id: correlation_id)
+
+    # Runs the block, converting Agentboard::Error into a failure envelope and any other
+    # exception into an opaque INTERNAL_ERROR (never leaking the original message).
+    def self.capture(correlation_id: Ids.correlation)
+      success(yield, correlation_id: correlation_id)
+    rescue Agentboard::Error => e
+      failure(e, correlation_id: correlation_id)
+    rescue ActiveRecord::StaleObjectError => e
+      failure(Error.version_conflict("Record was modified concurrently; reload and retry"), correlation_id: correlation_id)
+    rescue ActiveRecord::RecordNotFound
+      failure(Error.not_found("Record not found"), correlation_id: correlation_id)
+    rescue ActiveRecord::RecordInvalid => e
+      failure(Error.validation_failed(e.record.errors.full_messages.to_sentence), correlation_id: correlation_id)
+    rescue StandardError => e
+      Agentboard.logger.error("[agentboard] #{correlation_id} #{e.class}: #{Redactor.redact(e.message)}")
+      failure(Error.internal_error("Internal error (correlation #{correlation_id})"), correlation_id: correlation_id)
+    end
+
+    def initialize(data: nil, error: nil, correlation_id:)
+      @data = data
+      @error = error
+      @correlation_id = correlation_id
+    end
+
+    def ok? = error.nil?
+
+    def to_h
+      if ok?
+        { ok: true, data: data, correlation_id: correlation_id }
+      else
+        { ok: false, error: error.to_h, correlation_id: correlation_id }
+      end
+    end
+
+    def to_json(*args) = to_h.to_json(*args)
+  end
+end

data/lib/agentboard/runtime/ipc.rb

@@ -0,0 +1,193 @@
+require "socket"
+
+module Agentboard
+  module Runtime
+    # Local runtime IPC (spec §27.2): Unix domain socket in a user-private directory (0700),
+    # socket file 0600, plus a per-daemon bearer token (0600) checked on every request.
+    # Frames are 4-byte big-endian length + JSON, with a protocol version and size limit.
+    module IPC
+      PROTOCOL_VERSION = 1
+      MAX_MESSAGE_BYTES = 1024 * 1024
+
+      module_function
+
+      def paths(config = Agentboard.config)
+        dir = config.runtime_dir
+        id = Digest::SHA256.hexdigest(config.root_path.to_s)[0, 12]
+        { dir: dir, socket: dir.join("#{id}.sock"), token: dir.join("#{id}.token"), pid: dir.join("#{id}.pid"), log: dir.join("#{id}.log") }
+      end
+
+      def ensure_private_dir!(dir)
+        FileUtils.mkdir_p(dir, mode: 0o700)
+        stat = File.stat(dir)
+        raise Error.forbidden("Runtime directory #{dir} is not owned by the current user") unless stat.owned?
+
+        File.chmod(0o700, dir)
+      end
+
+      def write_frame(io, obj)
+        data = JSON.generate(obj)
+        raise Error.validation_failed("IPC message too large") if data.bytesize > MAX_MESSAGE_BYTES
+
+        io.write([ data.bytesize ].pack("N") + data)
+      end
+
+      def read_frame(io, timeout: 10)
+        header = read_exact(io, 4, timeout)
+        return nil unless header
+
+        size = header.unpack1("N")
+        raise Error.validation_failed("IPC message too large") if size > MAX_MESSAGE_BYTES
+
+        JSON.parse(read_exact(io, size, timeout) || raise(Error.validation_failed("truncated IPC frame")))
+      end
+
+      def read_exact(io, n, timeout)
+        buf = +""
+        while buf.bytesize < n
+          return nil unless IO.select([ io ], nil, nil, timeout)
+
+          chunk = io.read_nonblock(n - buf.bytesize, exception: false)
+          return nil if chunk.nil?
+          next if chunk == :wait_readable
+
+          buf << chunk
+        end
+        buf
+      end
+
+      class Server
+        def initialize(handler:, config: Agentboard.config, logger: Agentboard.logger)
+          @handler = handler
+          @paths = IPC.paths(config)
+          @logger = logger
+          @running = false
+        end
+
+        def start
+          IPC.ensure_private_dir!(@paths[:dir])
+          File.delete(@paths[:socket]) if File.socket?(@paths[:socket])
+          @token = Ids.token
+          File.write(@paths[:token], @token, perm: 0o600)
+          File.chmod(0o600, @paths[:token])
+          old = File.umask(0o177)
+          @server = UNIXServer.new(@paths[:socket].to_s)
+          File.umask(old)
+          File.chmod(0o600, @paths[:socket])
+          @running = true
+          @thread = Thread.new { accept_loop }
+          self
+        end
+
+        def stop
+          @running = false
+          @server&.close
+          File.delete(@paths[:socket]) if File.socket?(@paths[:socket])
+          File.delete(@paths[:token]) if File.exist?(@paths[:token])
+        rescue SystemCallError, IOError
+          nil
+        end
+
+        private
+
+        def accept_loop
+          while @running
+            client = @server.accept
+            Thread.new(client) { |c| serve(c) }
+          end
+        rescue IOError, Errno::EBADF
+          nil
+        end
+
+        def serve(client)
+          request = IPC.read_frame(client)
+          return unless request
+
+          response = dispatch(request)
+          IPC.write_frame(client, response)
+        rescue StandardError => e
+          IPC.write_frame(client, { "ok" => false, "error" => { "code" => "INTERNAL_ERROR", "message" => e.class.name } }) rescue nil
+        ensure
+          client.close
+        end
+
+        def dispatch(request)
+          unless request["protocol"] == PROTOCOL_VERSION
+            return { "ok" => false, "error" => { "code" => "VALIDATION_FAILED", "message" => "unsupported protocol #{request["protocol"].inspect}" } }
+          end
+          presented = request["token"].to_s
+          unless presented.bytesize == @token.bytesize && OpenSSL.fixed_length_secure_compare(presented, @token)
+            @logger.warn("[agentboard] rejected unauthenticated IPC request")
+            return { "ok" => false, "error" => { "code" => "UNAUTHORIZED", "message" => "invalid runtime credential" } }
+          end
+
+          result = Result.capture(correlation_id: request["correlation_id"].presence || Ids.correlation) do
+            @handler.call(request["op"].to_s, request["params"] || {})
+          end
+          JSON.parse(result.to_json)
+        end
+      end
+
+      class Client
+        def initialize(config: Agentboard.config)
+          @paths = IPC.paths(config)
+        end
+
+        def available? = File.socket?(@paths[:socket]) && File.exist?(@paths[:token])
+
+        def call(op, params = {}, timeout: 30)
+          raise Error.provider_unavailable("Runtime daemon is not running (agentboard daemon start)") unless available?
+
+          token = File.read(@paths[:token]).strip
+          UNIXSocket.open(@paths[:socket].to_s) do |sock|
+            IPC.write_frame(sock, { "protocol" => PROTOCOL_VERSION, "op" => op, "params" => params, "token" => token, "correlation_id" => Ids.correlation })
+            IPC.read_frame(sock, timeout: timeout) || raise(Error.provider_unavailable("No response from runtime"))
+          end
+        rescue Errno::ECONNREFUSED, Errno::ENOENT
+          raise Error.provider_unavailable("Runtime daemon is not reachable")
+        end
+      end
+    end
+
+    # Daemon lifecycle helpers: PID record with liveness validation (never trust a PID file alone).
+    module DaemonControl
+      module_function
+
+      def status(config = Agentboard.config)
+        paths = IPC.paths(config)
+        pid = File.exist?(paths[:pid]) ? File.read(paths[:pid]).to_i : nil
+        alive = pid && pid.positive? && Subprocess.alive?(pid)
+        health = nil
+        if alive && IPC::Client.new(config: config).available?
+          response = IPC::Client.new(config: config).call("runtime.health", {}, timeout: 3) rescue nil
+          health = response && response["ok"] ? response["data"] : nil
+        end
+        { running: !!(alive && health), pid: alive ? pid : nil, stale_pid_file: pid && !alive, health: health, socket: paths[:socket].to_s, log: paths[:log].to_s }
+      end
+
+      def write_pid!(config = Agentboard.config)
+        paths = IPC.paths(config)
+        IPC.ensure_private_dir!(paths[:dir])
+        lock = File.open(paths[:pid], File::RDWR | File::CREAT, 0o600)
+        raise Error.workspace_conflict("Another AgentBoard daemon is running for this project") unless lock.flock(File::LOCK_EX | File::LOCK_NB)
+
+        lock.truncate(0)
+        lock.write(::Process.pid.to_s)
+        lock.flush
+        lock # keep open to hold the lock for the daemon lifetime
+      end
+
+      def stop(config = Agentboard.config, timeout: 20)
+        st = status(config)
+        return false unless st[:pid]
+
+        ::Process.kill("TERM", st[:pid])
+        deadline = Subprocess.monotonic + timeout
+        sleep 0.1 while Subprocess.alive?(st[:pid]) && Subprocess.monotonic < deadline
+        !Subprocess.alive?(st[:pid])
+      rescue Errno::ESRCH
+        true
+      end
+    end
+  end
+end

data/lib/agentboard/runtime.rb

@@ -0,0 +1 @@
+require "agentboard/runtime/ipc"

data/lib/agentboard/state_machines.rb

@@ -0,0 +1,71 @@
+module Agentboard
+  # Pure transition tables. Guards that need persistence (leases, evidence, approvals)
+  # are enforced by the domain services in app/services/agentboard.
+  module StateMachines
+    module Ticket
+      STATES = %w[backlog ready claimed in_progress testing review done blocked cancelled reopened].freeze
+      TERMINAL = %w[done cancelled].freeze
+      NONTERMINAL = (STATES - TERMINAL).freeze
+      BOARD_COLUMNS = %w[backlog ready claimed in_progress testing review done].freeze
+
+      # spec §24.1 — anything not listed is INVALID_TRANSITION
+      TRANSITIONS = {
+        "backlog" => %w[ready blocked cancelled],
+        "ready" => %w[claimed blocked cancelled backlog],
+        "claimed" => %w[in_progress ready blocked cancelled],
+        "in_progress" => %w[testing blocked cancelled],
+        "testing" => %w[review in_progress blocked cancelled],
+        "review" => %w[done in_progress blocked cancelled],
+        "blocked" => %w[ready cancelled],
+        "reopened" => %w[ready blocked cancelled],
+        "done" => %w[reopened],
+        "cancelled" => []
+      }.freeze
+
+      LABELS = {
+        "backlog" => "Backlog", "ready" => "Ready", "claimed" => "Claimed", "in_progress" => "In progress",
+        "testing" => "Testing", "review" => "Review", "done" => "Done", "blocked" => "Blocked",
+        "cancelled" => "Cancelled", "reopened" => "Reopened"
+      }.freeze
+
+      module_function
+
+      def allowed?(from, to) = TRANSITIONS.fetch(from.to_s, []).include?(to.to_s)
+      def next_states(from) = TRANSITIONS.fetch(from.to_s, [])
+
+      def assert!(from, to)
+        return if allowed?(from, to)
+
+        raise Error.invalid_transition("Ticket cannot move from #{from} to #{to}", from: from, to: to)
+      end
+    end
+
+    module Execution
+      STATES = %w[queued preparing running waiting_for_input waiting_for_permission verifying completed failed cancelled interrupted].freeze
+      TERMINAL = %w[completed failed cancelled interrupted].freeze
+      ACTIVE = (STATES - TERMINAL).freeze
+
+      # spec §24.2
+      TRANSITIONS = {
+        "queued" => %w[preparing cancelled failed],
+        "preparing" => %w[running failed cancelled interrupted],
+        "running" => %w[verifying waiting_for_input waiting_for_permission failed cancelled interrupted],
+        "waiting_for_input" => %w[running failed cancelled interrupted],
+        "waiting_for_permission" => %w[running failed cancelled interrupted],
+        "verifying" => %w[completed failed cancelled interrupted],
+        "completed" => [], "failed" => [], "cancelled" => [], "interrupted" => []
+      }.freeze
+
+      module_function
+
+      def allowed?(from, to) = TRANSITIONS.fetch(from.to_s, []).include?(to.to_s)
+      def terminal?(state) = TERMINAL.include?(state.to_s)
+
+      def assert!(from, to)
+        return if allowed?(from, to)
+
+        raise Error.invalid_transition("Execution cannot move from #{from} to #{to}", from: from, to: to)
+      end
+    end
+  end
+end