hecks 4.0.0 → 6.0.0

data/lib/hecks/bulk/sweep.rb

@@ -0,0 +1,67 @@
+require_relative "../runtime/caller"
+require_relative "../runtime/dispatcher"
+require_relative "../runtime/row_sweep"
+require_relative "plan"
+require_relative "set_sweep"
+
+module Hecks
+  module Bulk
+    # One bulk run carried out: reads the rows of the run's query once, then sends the run's
+    # command to each row through {Runtime::RowSweep}, under the caller the run was asked by
+    # (ADR 0125). Answers one outcome per row in the order the query answered them.
+    class Sweep
+      # @param registry [Runtime::Registry] the registry the run's domain is booted in
+      # @param plan [Bulk::Plan] the run
+      # @param set_transform [Boolean] whether the run may go as one statement when its store
+      #   provides `set_transform` (ADR 0129); false sends every row by hand
+      def initialize(registry, plan, set_transform: true)
+        @registry   = registry
+        @plan       = plan
+        @set_transform = set_transform
+        @rows       = Runtime::RowSweep.new(registry)
+        @dispatcher = Runtime::Dispatcher.new(registry)
+        @origin     = Runtime::Caller.origin
+      end
+
+      # Sends the command to every row and answers how each came out.
+      #
+      # @return [Array<Hash{Symbol => Object}>] one `{ row:, delivered: }` per row, with `reason:`
+      #   when it was not delivered
+      # @raise [Runtime::UnknownVerb] if the verb or the query does not resolve
+      # @raise [ArgumentError] if no key of the command addresses a row of the query
+      def outcomes
+        key, read_ids = prepare
+        as_requester { compiled_outcomes(key, read_ids) } || row_outcomes(key, read_ids.call)
+      end
+
+      private
+
+      # The key a row addresses the command by, and how to read the rows' identities once.
+      def prepare
+        domain, aggregate_name, query_name = @plan.query_route
+        aggregate = @rows.query_aggregate(domain, aggregate_name, verb: @plan.over)
+        key = @rows.addressing_key_for(@plan.verb, aggregate_name, label: "the bulk run's verb")
+
+        args = @plan.query_arguments(aggregate.query(query_name))
+        [key, -> { @rows.rows(domain, aggregate, query_name, args).map { |row| row[:id] } }]
+      end
+
+      def row_outcomes(key, ids) = ids.map { |id| send_row(id, key) }
+
+      # The run as one statement when it can be (ADR 0129), else nil.
+      def compiled_outcomes(key, read_ids)
+        return nil unless @set_transform
+
+        planner = SetPlanner.new(@registry, @plan, key)
+        statement = planner.statement
+        statement && SetSweep.new(@registry, @plan, planner, statement).outcomes(read_ids) { |id| send_row(id, key) }
+      end
+
+      def send_row(id, key)
+        as_requester { @rows.deliver({ row: id.to_s }) { @dispatcher.dispatch_flat(@plan.verb, key => id) } }
+      end
+
+      def as_requester(&) = Runtime::Caller.restoring(@origin, &)
+    end
+  end
+end

data/lib/hecks/cli/check_era.rb

@@ -1,4 +1,4 @@
-require_relative "../ports/persistence/plugins/era/expected_era"
+require_relative "expected_era"
 
 module Hecks
   module CLI
@@ -8,7 +8,7 @@ module Hecks
       # What a check found.
       #
       # @!attribute [r] verdict
-      #   @return [Runtime::EraCheck::ExpectedEra::Verdict] the era compared with the list
+      #   @return [CLI::ExpectedEra::Verdict] the era compared with the list
       # @!attribute [r] version
       #   @return [String] the gem version the host reports, empty when it reports none
       # @!attribute [r] line
@@ -24,17 +24,17 @@ module Hecks
       # @param timeout [Numeric] seconds allowed for connecting and for reading
       # @return [Finding] the comparison, whether or not the era is listed
       # @raise [Errno::ENOENT, Errno::EACCES] if the file cannot be read
-      # @raise [Runtime::EraCheck::ExpectedEra::Unreachable] if the host cannot be reached
-      # @raise [Runtime::EraCheck::ExpectedEra::BadResponse] if it answers no era
+      # @raise [CLI::ExpectedEra::Unreachable] if the host cannot be reached
+      # @raise [CLI::ExpectedEra::BadResponse] if it answers no era
       def assess(url, file, timeout:)
-        expected = Runtime::EraCheck::ExpectedEra
+        expected = CLI::ExpectedEra
         allowed  = expected.parse(File.read(file))
         document = expected.fetch_version(url, timeout: timeout)
         verdict  = expected.verdict(document.fetch("era"), allowed)
         Finding.new(verdict, document.fetch("version"), sentence(verdict, file))
       end
 
-      # @param verdict [Runtime::EraCheck::ExpectedEra::Verdict] the comparison
+      # @param verdict [CLI::ExpectedEra::Verdict] the comparison
       # @param file [String] the allow-list file, named in the sentence
       # @return [String] the one line that says what the comparison found
       def sentence(verdict, file)

data/lib/hecks/cli/command_table.rb

@@ -50,8 +50,8 @@ module Hecks
       ),
       "project_diagrams" => Command.new(
         "Write a domain's Mermaid diagrams under ./docs/generated/diagrams/ (positional form only).",
-        "hecks project_diagrams <domain-path> <ChapterName>  (writes) | " \
-        "hecks project_diagrams domain=<path> chapter=<Name>  (prints; writes nothing)",
+        "hecks project_diagrams <domain-path> <BluebookName>  (writes) | " \
+        "hecks project_diagrams domain=<path> bluebook=<Name>  (prints; writes nothing)",
         "cli/project_diagrams",
         ->(argv, program, _name) { ProjectDiagrams.call(argv, program: program, root: Dir.pwd) }
       ),

data/lib/hecks/cli/console.rb

@@ -48,18 +48,23 @@ module Hecks
       end
 
       # @param runtime [Runtime] a booted domain
-      # @return [String] each chapter's vision, and its aggregates' descriptions and commands
+      # @return [String] each bluebook's vision, and its aggregates' descriptions and commands
       def overview(runtime)
-        runtime.registry.bluebooks.each_value.map do |bluebook|
-          aggregates = bluebook.aggregates.map { |aggregate| aggregate_overview(aggregate) }
+        declarations = runtime.bluebooks.each_value.map { |bluebook| bluebook_overview(bluebook) }
+        declarations.join
+      end
+
+      # @api private
+      def bluebook_overview(bluebook)
+        aggregates = bluebook.aggregates.map { |aggregate| aggregate_overview(aggregate) }
 
-          "\n    #{bluebook.name} — #{bluebook.vision}\n#{aggregates.join("\n")}\n"
-        end.join
+        "\n    #{bluebook.name} — #{bluebook.vision}\n#{aggregates.join("\n")}\n"
       end
 
       # @api private
       def aggregate_overview(aggregate)
-        commands = aggregate.commands.map { |command| "#{Naming.snake(command.hecks_name)}!" }.sort.join(", ")
+        verbs = aggregate.commands.map { |command| "#{Naming.snake(command.hecks_name)}!" }
+        commands = verbs.sort.join(", ")
         description = aggregate.description.to_s.strip
         lines = ["    #{aggregate.name}: #{commands}"]
         lines << "      #{description}" unless description.empty?

data/lib/hecks/cli/document.rb

@@ -38,7 +38,7 @@ module Hecks
         end
       end
 
-      # The domain's own chapter, not a framework member it attached: insertion
+      # The domain's own bluebook, not a framework member it attached: insertion
       # order, the same distinction `Runtime::Loader.dispatcher_for` draws.
       #
       # @api private
@@ -46,26 +46,31 @@ module Hecks
         begin
           runtime = Hecks.boot(path, install_driving: false)
         rescue StandardError => e
-          abort "cannot read #{path}: #{e.message.lines.first.strip}"
+          abort "cannot read #{path}: #{Text.first_line(e.message)}"
         end
 
-        runtime.registry.bluebooks.values.first or abort "#{path} loaded no bluebook"
+        runtime.first_bluebook or abort "#{path} loaded no bluebook"
       end
 
       # Lists every directory under `root` that `Hecks.boot` would accept.
       #
-      # Found by their wiring, not their chapters: a `.hecksagon` says this is a
+      # Found by their wiring, not their bluebooks: a `.hecksagon` says this is a
       # domain, while most `.bluebook` files (era translations, grammar, fixtures) are not.
       #
       # @param root [String] the directory to search under
       # @return [Array<String>] domain directory paths relative to `root`,
       #   deduplicated and sorted
       def domains(root)
-        Dir.glob(File.join(root, "**/*.hecksagon"))
-           .map    { |path| File.basename(File.dirname(path)) == "bluebook" ? File.dirname(path, 2) : File.dirname(path) }
-           .map    { |path| path.delete_prefix("#{root}/") }
-           .grep_v(IGNORED)
-           .uniq.sort
+        wiring = Dir.glob(File.join(root, "**/*.hecksagon"))
+        relative = wiring.map { |path| domain_directory(path).delete_prefix("#{root}/") }
+        relative.grep_v(IGNORED).uniq.sort
+      end
+
+      # The domain directory a `.hecksagon` sits in: its parent, or the one above a `bluebook/`.
+      #
+      # @api private
+      def domain_directory(path)
+        File.basename(File.dirname(path)) == "bluebook" ? File.dirname(path, 2) : File.dirname(path)
       end
 
       # @api private

data/lib/hecks/cli/domain_writer.rb

@@ -6,6 +6,9 @@ module Hecks
     #
     # Every target is checked before the first is written, so a refusal leaves nothing half-written.
     module DomainWriter
+      # A bluebook directly inside the domain's `bluebook/` directory.
+      TOP_LEVEL_BLUEBOOK = %r{\Abluebook/[^/]+\.bluebook\z}
+
       module_function
 
       # @param files [Hash{String => String}] each file's path under the target, and its text
@@ -29,7 +32,7 @@ module Hecks
       # @return [Array<String>] the paths in the way, relative to the target
       def taken(files, target)
         taken = files.keys.select { |path| File.exist?(File.join(target, path)) }
-        if files.keys.any? { |path| path.match?(%r{\Abluebook/[^/]+\.bluebook\z}) }
+        if files.keys.any? { |path| path.match?(TOP_LEVEL_BLUEBOOK) }
           taken |= Dir.glob(File.join(target, "bluebook", "*.bluebook")).map { |full| full.delete_prefix("#{target}/") }
         end
         taken

data/lib/hecks/cli/expected_era.rb

@@ -0,0 +1,139 @@
+require "json"
+require "net/http"
+require "uri"
+
+module Hecks
+  module CLI
+    # Compares a running host's reported era (`GET /version`) against an
+    # allow-list file of eras that should be running, for use after a roll. It is the HTTP side of
+    # `hecks check_era`, which the `HostHttp` adapter runs; the runtime never calls it.
+    module ExpectedEra
+      # The host could not be reached, or did not answer with a `200`.
+      class Unreachable < StandardError; end
+
+      # The host answered, but not with a `/version` document carrying an era.
+      class BadResponse < StandardError; end
+
+      # What a comparison concluded.
+      #
+      # @!attribute [r] status
+      #   @return [Symbol] `:match`, `:unlisted` (no era listed) or `:mismatch`
+      # @!attribute [r] era
+      #   @return [String] the era the host reported
+      # @!attribute [r] allowed
+      #   @return [Array<String>] the eras the list accepts
+      Verdict = Struct.new(:status, :era, :allowed) do
+        # Tells whether the roll is acceptable.
+        #
+        # @return [Boolean] true unless the reported era is off the list
+        def ok? = status != :mismatch
+      end
+
+      # A trailing ` # comment` on an allow-list line.
+      TRAILING_COMMENT = /\s+#.*\z/
+
+      module_function
+
+      # Reads the eras out of an allow-list file's text.
+      #
+      # @param text [String] the file's contents
+      # @return [Array<String>] the era ids in file order, without comments or blanks
+      def parse(text)
+        text.each_line.filter_map do |line|
+          entry = line.strip.sub(TRAILING_COMMENT, "")
+          entry unless entry.empty? || entry.start_with?("#")
+        end
+      end
+
+      # Builds the `/version` URL from what an operator gave.
+      #
+      # @param url [String] a host's base URL, or its `/version` URL itself
+      # @return [String] the URL to request
+      def version_url(url)
+        base = url.to_s.chomp("/")
+        base.end_with?("/version") ? base : "#{base}/version"
+      end
+
+      # Asks a host which era it reports.
+      #
+      # @param url [String] the host's base URL, or its `/version` URL
+      # @param timeout [Numeric] seconds allowed for connecting and for reading
+      # @return [String] the `era` the host's `/version` document carries
+      # @raise [Unreachable] if the request fails or the status is not `200`
+      # @raise [BadResponse] if the body is not JSON or its `era` is not a non-empty string
+      def fetch_era(url, timeout:)
+        fetch_version(url, timeout: timeout).fetch("era")
+      end
+
+      # Asks a host for its `/version` document.
+      #
+      # @param url [String] the host's base URL, or its `/version` URL
+      # @param timeout [Numeric] seconds allowed for connecting and for reading
+      # @return [Hash{String => String}] `"era"` (never empty) and `"version"` (empty when the
+      #   host reports none)
+      # @raise [Unreachable] if the request fails or the status is not `200`
+      # @raise [BadResponse] if the body is not JSON or its `era` is not a non-empty string
+      def fetch_version(url, timeout:)
+        target = version_url(url)
+        response = get(target, timeout)
+        raise Unreachable, "#{target} answered #{response.code}" unless response.code == "200"
+
+        document = JSON.parse(response.body)
+        { "era" => era_in(document, target), "version" => document["version"].to_s }
+      rescue JSON::ParserError, TypeError
+        raise BadResponse, "#{version_url(url)} did not answer a JSON version document"
+      end
+
+      # Reads the era out of a parsed `/version` document.
+      #
+      # @param document [Hash] the parsed document
+      # @param target [String] the URL it came from, named in the refusal
+      # @return [String] the non-empty era
+      # @raise [BadResponse] if the era is not a non-empty string
+      def era_in(document, target)
+        era = document["era"]
+        raise BadResponse, "#{target} carries no era" unless era.is_a?(String) && !era.empty?
+
+        era
+      end
+
+      # Compares a reported era with an allow-list.
+      #
+      # @param era [String] the era the host reported
+      # @param allowed [Array<String>] the eras the list accepts; empty accepts any
+      # @return [Verdict] `:unlisted` when the list is empty, else `:match` or `:mismatch`
+      def verdict(era, allowed)
+        status = if allowed.empty? then :unlisted
+                 elsif allowed.include?(era) then :match
+                 else :mismatch
+                 end
+        Verdict.new(status, era, allowed)
+      end
+
+      # Fetches the host's era and compares it with an allow-list file.
+      #
+      # @param url [String] the host's base URL, or its `/version` URL
+      # @param file [String] path of the allow-list file
+      # @param timeout [Numeric] seconds allowed for connecting and for reading
+      # @return [Verdict] the comparison
+      # @raise [Errno::ENOENT] if the allow-list file does not exist
+      # @raise [Unreachable] see `fetch_era`
+      # @raise [BadResponse] see `fetch_era`
+      def check(url, file, timeout:)
+        allowed = parse(File.read(file))
+        verdict(fetch_era(url, timeout: timeout), allowed)
+      end
+
+      def get(url, timeout)
+        uri = URI.parse(url)
+        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                            open_timeout: timeout, read_timeout: timeout) do |http|
+          http.request(Net::HTTP::Get.new(uri.request_uri, "Accept" => "application/json"))
+        end
+      rescue SystemCallError, SocketError, Timeout::Error, IOError, URI::InvalidURIError => e
+        raise Unreachable, "#{url} could not be reached: #{e.message}"
+      end
+      private_class_method :get
+    end
+  end
+end

data/lib/hecks/cli/expression_projection.rb

@@ -5,12 +5,12 @@ require_relative "../projection_files"
 module Hecks
   module CLI
     # The command behind `hecks project_expression_tables`: projects the expression machinery's
-    # operator and normalisation tables from the grammar chapter into
+    # operator and normalisation tables from the grammar bluebook into
     # `lib/hecks/bluebook/expression/projection.json`.
     #
     # It never redirects with `>`: the shell would truncate the file the framework requires at
     # boot. The default mode replaces the file atomically, and it refuses a projection that drops
-    # a self-bearing operator (one the chapter's own `status != "retired"` givens evaluate
+    # a self-bearing operator (one the bluebook's own `status != "retired"` givens evaluate
     # through), since that would wedge every later boot. Recover a broken file with
     # `git checkout -- lib/hecks/bluebook/expression/projection.json`.
     module ExpressionProjection

data/lib/hecks/cli/follow.rb

@@ -49,8 +49,8 @@ module Hecks
       # @return [Object] the first repository that answers `:events`
       # @raise [SystemExit] when none does
       def event_repository(runtime, domain_name, program)
-        repositories = runtime.registry.bluebooks.flat_map do |bluebook_domain, bluebook|
-          bluebook.aggregates.map { |aggregate| runtime.registry.repository(bluebook_domain, aggregate) }
+        repositories = runtime.bluebooks.flat_map do |bluebook_domain, bluebook|
+          bluebook.aggregates.map { |aggregate| runtime.repository(bluebook_domain, aggregate) }
         end
         repositories.find { |repo| repo.respond_to?(:events) } or
           abort "#{program}: no adapter in #{domain_name} persists an event log"
@@ -63,7 +63,7 @@ module Hecks
       # @param filter [String, nil] the aggregate name asked for
       # @return [Boolean]
       def matches?(event, filter)
-        filter.nil? || event.aggregate.to_s.split("::").last.casecmp?(filter) || event.aggregate == filter
+        filter.nil? || Naming.demodulise(event.aggregate).casecmp?(filter) || event.aggregate == filter
       end
 
       # @param repository [Object] answers `events`

data/lib/hecks/cli/history.rb

@@ -2,6 +2,7 @@
 
 require "json"
 require_relative "../../hecks"
+require_relative "persistence_notice"
 
 module Hecks
   module CLI
@@ -18,7 +19,9 @@ module Hecks
       # @raise [SystemExit] when `argv` is empty
       def call(argv, program: "hecks history")
         domain = argv.first or abort "usage: #{program} <domain>"
-        puts JSON.generate(document(Hecks.boot(domain).registry))
+        registry = Hecks.boot(domain).registry
+        PersistenceNotice.announce(registry, program: program)
+        puts JSON.generate(document(registry))
       end
 
       # @param registry [Runtime::Registry] a booted domain's registry

data/lib/hecks/cli/interview_draft.rb

@@ -17,6 +17,10 @@ module Hecks
     # turned into code from prose: it is a comment citing its source, to become a `given` by hand.
     module InterviewDraft
       ACCEPTED = "accepted".freeze
+      # A run of anything but letters and digits: the gaps between the words of a free-text name.
+      NAME_GAP = /[^A-Za-z0-9]+/
+      # The first character of a word.
+      INITIAL = /\A./
 
       extend InterviewRecord
       extend InterviewAggregate
@@ -96,7 +100,10 @@ module Hecks
 
       # A free-text name as a PascalCase word safe to write into Ruby: `lend a book` is `LendABook`.
       # @api private
-      def word(text) = text.to_s.split(/[^A-Za-z0-9]+/).reject(&:empty?).map { |part| part.sub(/\A./, &:upcase) }.join
+      def word(text)
+        parts = text.to_s.split(NAME_GAP).reject(&:empty?)
+        parts.map { |part| part.sub(INITIAL, &:upcase) }.join
+      end
 
       # @api private
       def cite(interview, finding) = "#{interview[:reference]} ##{finding[:source]}:"

data/lib/hecks/cli/interview_record.rb

@@ -1,3 +1,5 @@
+require_relative "../text"
+
 module Hecks
   module CLI
     # The Markdown record of an interview, and the plain interview read out of a booted record.
@@ -11,6 +13,8 @@ module Hecks
         fields:      [:number, :thing, :name, :values, :source, :status],
         transitions: [:number, :thing, :action, :to, :from, :source, :status]
       }.freeze
+      # Any character a record's file name may not carry.
+      UNSAFE_FILE_CHARACTER = /[^A-Za-z0-9._-]/
 
       # The interview's record: every exchange in order, and every finding with how it was decided.
       #
@@ -25,7 +29,7 @@ module Hecks
         "#{lines.join("\n")}\n"
       end
 
-      # Reads the plain interview out of an `Interview` record booted from the SME chapter.
+      # Reads the plain interview out of an `Interview` record booted from the SME bluebook.
       #
       # @param interview [Object] the booted record
       # @return [Hash] the plain interview this module takes: `reference`, `subject`, `expert`,
@@ -51,7 +55,7 @@ module Hecks
       end
 
       # @api private
-      def file_stem(reference) = reference.to_s.gsub(/[^A-Za-z0-9._-]/, "_")
+      def file_stem(reference) = reference.to_s.gsub(UNSAFE_FILE_CHARACTER, "_")
 
       # @api private
       def exchange_lines(exchange, number)
@@ -113,7 +117,7 @@ module Hecks
       def clause(label, value) = value.to_s.strip.empty? ? "" : ", #{label} #{value}"
 
       # @api private
-      def one_line(text) = text.to_s.gsub(/\s+/, " ").strip
+      def one_line(text) = text.to_s.gsub(Text::WHITESPACE, " ").strip
 
       # @api private
       def plain(value)

data/lib/hecks/cli/interview_run.rb

@@ -6,9 +6,10 @@ require_relative "interview_session"
 
 module Hecks
   module CLI
-    # The command behind `hecks interview <Name>` (ADR 0088): boots the SME chapter on demand, holds
-    # the interview at the terminal, then writes the first domain, or the next interview's proposed
-    # additions, and says what to type next. Nothing is written unless the interview concludes.
+    # The command behind `hecks interview <Name>` (ADR 0088): boots the SME bluebook on demand,
+    # holds the interview at the terminal, then writes the first domain, or the next interview's
+    # proposed additions, and says what to type next. Nothing is written unless the interview
+    # concludes.
     module InterviewRun
       SME = File.expand_path("../sme", __dir__)
 
@@ -22,7 +23,7 @@ module Hecks
       # @param input [#gets] where the developer types
       # @param output [#puts, #print] where the session speaks
       # @param agent [#question, #proposals, nil] an interviewer to use instead of the real one
-      # @param runtime [Runtime, nil] a booted SME chapter to use instead of booting one
+      # @param runtime [Runtime, nil] a booted SME bluebook to use instead of booting one
       # @return [String] the report that was printed, or "" when nothing was written
       # @raise [ArgumentError] when the name or adapter is refused, or a file would be replaced
       def call(name:, adapter: nil, dir: nil, expert: nil, use_ai: true, input: $stdin, output: $stdout, agent: nil, # rubocop:disable Metrics/ParameterLists -- one keyword per setting the command takes
@@ -51,7 +52,8 @@ module Hecks
         return expert unless expert.to_s.strip.empty?
 
         output.print("Who is the expert? ")
-        input.gets.to_s.strip.then { |text| text.empty? ? "the expert" : text }
+        answer = input.gets.to_s.strip
+        answer.empty? ? "the expert" : answer
       end
 
       # @api private

data/lib/hecks/cli/interview_session/proposals.rb

@@ -2,8 +2,11 @@ module Hecks
   module CLI
     class InterviewSession
       # Putting an agent's proposed finding to the developer: reading its fields, proposing it to
-      # the SME chapter, describing it, and recording the decision.
+      # the SME bluebook, describing it, and recording the decision.
       module Proposals
+        # The `Something refused — ` a refusal message opens with.
+        REFUSAL_LEAD = /\A[A-Z]\w* refused\s+[—-]\s+/
+
         private
 
         def review(proposal)
@@ -83,7 +86,7 @@ module Hecks
           "#{", taking #{fields["takes"]}" if fields["takes"]}#{", by #{fields["by"]}" if fields["by"]}"
         end
 
-        def reason(error) = error.message.sub(/\A[A-Z]\w* refused\s+[—-]\s+/, "").strip
+        def reason(error) = error.message.sub(REFUSAL_LEAD, "").strip
       end
     end
   end

data/lib/hecks/cli/interview_session.rb

@@ -1,3 +1,4 @@
+require_relative "../text"
 require_relative "interview_draft"
 require_relative "interview_session/catalog"
 require_relative "interview_session/proposals"
@@ -20,7 +21,7 @@ module Hecks
       include ManualFindings
       include AgentState
 
-      # @param runtime [Runtime] the booted SME chapter
+      # @param runtime [Runtime] the booted SME bluebook
       # @param agent [#question, #proposals, nil] the interviewer; nil runs the plain prompts
       # @param input [#gets] where the developer types
       # @param output [#puts, #print] where the session speaks
@@ -104,7 +105,7 @@ module Hecks
       def ask_agent
         yield
       rescue Ports::Agent::Unavailable, Ports::Agent::ValidationError => e
-        say("The AI could not answer (#{e.message.lines.first.to_s.strip}). Using a plain prompt for this turn.")
+        say("The AI could not answer (#{Text.first_line(e.message)}). Using a plain prompt for this turn.")
         nil
       end
 

data/lib/hecks/cli/interview_shape/lifecycle.rb

@@ -0,0 +1,92 @@
+require_relative "../../text"
+
+module Hecks
+  module CLI
+    module InterviewShape
+      # The lifecycle an interview's accepted transitions describe, and the state words it is
+      # written in. `InterviewShape` extends it, so each method answers on `InterviewShape`.
+      module Lifecycle
+        # A run of anything a state word may not hold.
+        NON_STATE_CHARACTERS = /[^a-z0-9]+/
+        # An underscore at either end of a word.
+        EDGE_UNDERSCORE = /\A_|_\z/
+
+        # The lifecycle the accepted transitions describe. The state a creating action's step
+        # leads to is where a thing starts; a step for an action the thing does not have is kept
+        # as a comment.
+        #
+        # @param steps [Array<Hash>] the thing's accepted transitions
+        # @param creating [Array<Hash>] the accepted actions that create it
+        # @param rest [Array<Hash>] its other accepted actions
+        # @return [Array<String>] the lines, or none when no step and start state can be placed
+        def lifecycle(steps, creating, rest)
+          starts, moves = steps.partition { |step| names_action?(creating, step) }
+          placed, loose = moves.partition { |step| names_action?(rest, step) }
+          placed = merged(placed)
+          start = beginning(starts, placed)
+          return [] if start.empty? || placed.empty?
+
+          lifecycle_block(start, placed, loose)
+        end
+
+        # @api private
+        def lifecycle_block(start, placed, loose)
+          ["", "    lifecycle :status, default: #{start.inspect} do", *placed.map { |step| transition_line(step) },
+           "    end", *loose.map { |step| loose_line(step) }]
+        end
+
+        # @api private
+        def names_action?(actions, step)
+          actions.map { |action| InterviewDraft.word(action[:name]) }.include?(InterviewDraft.word(step[:action]))
+        end
+
+        # One step for each action and state it leads to: the states it starts from are joined,
+        # and a step with no state to start from means it may be taken from any.
+        # @api private
+        def merged(steps)
+          steps.group_by { |step| [InterviewDraft.word(step[:action]), state_word(step[:to])] }.values.map do |group|
+            froms = group.map { |step| step[:from].to_s.strip }
+            group.first.merge(from: froms.any?(&:empty?) ? "" : froms.join(","))
+          end
+        end
+
+        # The state a thing starts in: where its creating action's step leads, else the first state
+        # a change is said to start from.
+        # @api private
+        def beginning(starts, placed)
+          from = placed.map { |step| step[:from].to_s.split(",").first }.find { |text| !text.to_s.strip.empty? }
+          state_word(starts.first&.fetch(:to) || from)
+        end
+
+        # @api private
+        def transition_line(step)
+          "      transition #{InterviewDraft.word(step[:action]).inspect} => #{state_word(step[:to]).inspect}" \
+            "#{from_clause(step)}"
+        end
+
+        # @api private
+        def loose_line(step)
+          "    # UNPLACED transition: #{InterviewDraft.word(step[:action])} to #{state_word(step[:to])}; " \
+            "no accepted action has that name."
+        end
+
+        # The states a step may start from: none, one, or several.
+        # @api private
+        def from_clause(step)
+          froms = step[:from].to_s.split(Text::COMMA).map { |text| state_word(text) }
+          states = froms.reject(&:empty?)
+          return "" if states.empty?
+
+          states.one? ? ", from: #{states.first.inspect}" : ", from: %w[#{states.join(" ")}]"
+        end
+
+        # A state as a lowercase word: `Not Yet Triaged` is `not_yet_triaged`.
+        # @api private
+        def state_word(text)
+          lowered = text.to_s.strip.downcase
+          lowered.gsub(NON_STATE_CHARACTERS, "_").gsub(EDGE_UNDERSCORE, "")
+        end
+      end
+    end
+  end
+end