hecks 4.0.0 → 6.0.0

data/lib/hecks/forms/app.rb

@@ -16,12 +16,15 @@ module Hecks
       include Commands
       include Queries
 
-      # Builds the Rack app for a configured app name, exposing exactly the chapters its
+      # A path segment ending in a format extension, capturing the rest and the format.
+      FORMAT_SUFFIX = /\A(.*)\.(html|json)\z/
+
+      # Builds the Rack app for a configured app name, exposing exactly the bluebooks its
       # `Forms.configure` block declared.
       #
-      # @param registry [Runtime::Registry] the booted registry holding the exposed chapters
+      # @param registry [Runtime::Registry] the booted registry holding the exposed bluebooks
       # @param app_name [String, Symbol] the name an earlier `Forms.configure` call registered
-      # @return [Forms::App] a Rack app routing only the configured chapters
+      # @return [Forms::App] a Rack app routing only the configured bluebooks
       # @raise [ArgumentError] if no app of that name has been configured
       def self.for(registry:, app_name:)
         config = Forms.config(app_name) ||
@@ -30,8 +33,8 @@ module Hecks
         new(registry: registry, exposed: config.exposes)
       end
 
-      # @param registry [Runtime::Registry] the booted registry holding the exposed chapters
-      # @param exposed [Array<String>] names of the chapters (domains) this app routes; a
+      # @param registry [Runtime::Registry] the booted registry holding the exposed bluebooks
+      # @param exposed [Array<String>] names of the bluebooks (domains) this app routes; a
       #   request for any other domain is answered 404
       # @param dispatcher [Runtime::Dispatcher, nil] the dispatcher commands and queries go
       #   through; nil builds a `Runtime::Dispatcher` over `registry`
@@ -62,26 +65,26 @@ module Hecks
         segments = request.path_info.split("/").reject(&:empty?)
         return home(request) if segments.empty?
 
-        chapter = chapter_for(segments[0])
+        declaration = bluebook_for(segments[0])
         case segments.size
-        when 2 then aggregate_route(request, chapter, *split_format(segments[1]))
-        when 3 then verb_or_record_route(request, chapter, segments[1], *split_format(segments[2]))
-        else unrouted(request, chapter, segments)
+        when 2 then aggregate_route(request, declaration, *split_format(segments[1]))
+        when 3 then verb_or_record_route(request, declaration, segments[1], *split_format(segments[2]))
+        else unrouted(request, declaration, segments)
         end
       end
 
-      def unrouted(request, chapter, segments)
-        refuse_entity_command if segments.size == 4 && entity_command?(chapter, segments)
+      def unrouted(request, declaration, segments)
+        refuse_entity_command if segments.size == 4 && entity_command?(declaration, segments)
         respond(404, "text/plain", "no route for #{request.path_info}")
       end
 
-      def chapter_for(domain)
+      def bluebook_for(domain)
         refuse_unexposed(domain)
         @registry.bluebook(domain) || raise(RouteNotFound, "no domain #{domain.inspect} loaded")
       end
 
-      def entity_command?(chapter, segments)
-        entity = chapter.aggregate(segments[1])&.entities&.find { |candidate| candidate.hecks_name == segments[2] }
+      def entity_command?(declaration, segments)
+        entity = declaration.aggregate(segments[1])&.entities&.find { |candidate| candidate.hecks_name == segments[2] }
         !entity&.command(split_format(segments[3]).first).nil?
       end
 
@@ -94,24 +97,24 @@ module Hecks
       def refuse_unexposed(domain)
         return if @exposed.include?(domain)
 
-        raise RouteNotFound, "#{domain.inspect} is not exposed by this app — declared chapters: #{@exposed.join(", ")}"
+        raise RouteNotFound, "#{domain.inspect} is not exposed by this app — declared bluebooks: #{@exposed.join(", ")}"
       end
 
       # Only a trailing ".html"/".json" is a format; other dots belong to the identity
       # (an email, say). An identity ending in ".html" or ".json" stays ambiguous.
       def split_format(segment)
         segment = segment.to_s
-        return [Regexp.last_match(1), Regexp.last_match(2)] if segment =~ /\A(.*)\.(html|json)\z/
+        return [Regexp.last_match(1), Regexp.last_match(2)] if segment =~ FORMAT_SUFFIX
 
         [segment, "json"]
       end
 
       def home(request)
         format = request.params["format"] || "html"
-        chapters = @exposed.to_h { |name| [name, @registry.bluebook(name)] }.compact
-        return json(200, chapters.transform_values { |c| { aggregates: c.aggregates.map(&:hecks_name) } }) if format != "html"
+        declarations = @exposed.to_h { |name| [name, @registry.bluebook(name)] }.compact
+        return json(200, declarations.transform_values { |c| { aggregates: c.aggregates.map(&:hecks_name) } }) if format != "html"
 
-        html("Exposed domains", IndexRenderer.render(chapters))
+        html("Exposed domains", IndexRenderer.render(declarations))
       end
     end
   end

data/lib/hecks/forms/command_form_renderer.rb

@@ -147,7 +147,7 @@ module Hecks
 
         <<~HTML
           <div class="error-banner" role="alert">
-            <p><strong>Refused (#{Escape.html(error.class.name.split("::").last)}):</strong> #{Escape.html(error.message)}</p>
+            <p><strong>Refused (#{Escape.html(Naming.demodulise(error.class.name))}):</strong> #{Escape.html(error.message)}</p>
           </div>
         HTML
       end
@@ -165,7 +165,7 @@ module Hecks
       # Renders the collapsed "Inspect" panel: the events the command emits, an equivalent
       # `curl` request, its field paths, and its declaration as JSON.
       #
-      # @param domain [String] name of the domain (chapter) the aggregate belongs to
+      # @param domain [String] name of the domain (bluebook) the aggregate belongs to
       # @param aggregate [Bluebook::Aggregate] the aggregate that declares the command
       # @param command [Bluebook::Command] the command being described
       # @param action [String] URL path the form posts to, shown in the `curl` line

data/lib/hecks/forms/field_controls.rb

@@ -1,4 +1,5 @@
 require_relative "html"
+require_relative "html_pattern"
 require_relative "../naming"
 
 module Hecks
@@ -23,7 +24,11 @@ module Hecks
         end
 
         # A :reference input takes a record id, so the attribute's own pattern must not apply.
-        def self.leaf_pattern(field) = field.kind == :reference ? nil : field.pattern
+        def self.leaf_pattern(field) = field.kind == :reference ? nil : html_pattern(field.pattern)
+
+        # @param pattern [String, nil] the attribute's pattern
+        # @return [String, nil] the pattern as the input should carry it (see `HtmlPattern`)
+        def self.html_pattern(pattern) = HtmlPattern.for(pattern)
 
         def self.preview_target(field) = "##{FieldRenderer.dom_id(field.path)}-preview"
 

data/lib/hecks/forms/field_shape.rb

@@ -24,10 +24,17 @@ module Hecks
 
     # Turns a wire-spelled field or path segment into a label or legend.
     module Humanize
+      # A leading run of two or more capitals: an acronym that keeps its case.
+      LEADING_ACRONYM = /\A[A-Z]{2,}\b/
+
+      # The first character of a phrase.
+      FIRST_CHARACTER = /\A./
+
       # "daily_limit" -> "Daily limit"; only the last segment of a dotted path is used.
       def self.label(text)
         # Split on "." alone: an underscore is a word break within a segment, not a path hop.
-        segment = text.to_s.split(".").last.to_s
+        segments = text.to_s.split(".")
+        segment = segments.last.to_s
         return segment if segment.empty?
 
         Naming.words(segment)
@@ -46,7 +53,7 @@ module Hecks
       # @return [String] the words, the first lowercased unless it is an acronym
       def self.noun(name)
         words = Naming.words(name)
-        words.match?(/\A[A-Z]{2,}\b/) ? words : words.sub(/\A./, &:downcase)
+        words.match?(LEADING_ACRONYM) ? words : words.sub(FIRST_CHARACTER, &:downcase)
       end
     end
 
@@ -57,7 +64,7 @@ module Hecks
       # Resolves one declared attribute into the field a form renders for it.
       #
       # `aggregate` owns the attribute and is needed to resolve `reference_to`, `admits:`
-      # and same-chapter value objects; `path` is the dotted path reached so far.
+      # and same-bluebook value objects; `path` is the dotted path reached so far.
       #
       # @param attribute [Bluebook::Attribute]
       # @param aggregate [Bluebook::Aggregate]
@@ -90,12 +97,12 @@ module Hecks
       end
 
       def self.reference_field(attribute, common)
-        target = attribute.type.resolve
+        target = attribute.target_aggregate
         help = target ? "An existing #{Humanize.noun(target.hecks_name)}, by its id." : "A record in another domain, by its id."
         Field.new(**common, kind: :reference, html_type: "text", target_aggregate: target, help: help)
       end
 
-      # Mirrors Runtime::Value::Admission#admitted_members (same split, chapter walk and
+      # Mirrors Runtime::Value::Admission#admitted_members (same split, bluebook walk and
       # discriminant rule) so a `<select>` never offers a member the runtime would refuse.
       def self.admitted_field(attribute, aggregate, common)
         set = admitted_set(attribute, aggregate)
@@ -148,7 +155,8 @@ module Hecks
       end
 
       def self.cross_aggregate_value_object(aggregate, type_name)
-        aggregate.hecks_owner&.aggregates&.each do |sibling|
+        owner = aggregate.hecks_owner
+        owner&.aggregates&.each do |sibling|
           found = sibling.value_object(type_name)
           return found if found
         end

data/lib/hecks/forms/html.rb

@@ -5,20 +5,21 @@ module Hecks
     # HTML, URL-query and URL-path escaping for values that come from domain data.
     # Nothing that reaches `Escape.html` becomes a tag.
     module Escape
+      # A character HTML text content must not hold as itself.
+      HTML_SPECIAL = /[&<>"']/
+
+      # The entity each `HTML_SPECIAL` character is written as.
+      HTML_ENTITIES = { "&" => "&amp;", "<" => "&lt;", ">" => "&gt;", '"' => "&quot;", "'" => "&#39;" }.freeze
+
       # Escapes a value for HTML text content, replacing `&`, `<`, `>`, `"` and `'` with
       # entities so nothing in it becomes a tag.
       #
-      # `&` is replaced first so the entities written here are not escaped again.
+      # One pass over the text, so the entities written here are not escaped again.
       #
       # @param value [Object, nil] the value to show, rendered with `to_s`; nil renders as `""`
       # @return [String] the escaped text
       def self.html(value)
-        value.to_s
-             .gsub("&", "&amp;")
-             .gsub("<", "&lt;")
-             .gsub(">", "&gt;")
-             .gsub('"', "&quot;")
-             .gsub("'", "&#39;")
+        value.to_s.gsub(HTML_SPECIAL, HTML_ENTITIES)
       end
 
       # Escapes a value for use inside a quoted HTML attribute.

data/lib/hecks/forms/html_pattern.rb

@@ -0,0 +1,80 @@
+require "strscan"
+
+module Hecks
+  module Forms
+    # An attribute's pattern as an input's `pattern` attribute carries it.
+    #
+    # The domain reads a pattern as Ruby and finds it anywhere in a value; a browser reads the
+    # `pattern` attribute as JavaScript, in its `v` mode, and holds it to the whole value. So the
+    # pattern is wrapped to be found anywhere, which keeps `^https?://` from accepting only the
+    # scheme and `[^ \t\n\r]` from accepting one character, and what Ruby spells differently is
+    # rewritten: `\A` and `\z` as `^` and `$`, `\h` as a hex range, and inside a character class a
+    # literal `-`, `(`, `)`, `{`, `}`, `|` and `/` escaped, which `v` mode refuses bare. A browser
+    # ignores a pattern it cannot compile, so a pattern left as Ruby wrote it is not checked at all.
+    class HtmlPattern
+      # What Ruby writes outside a character class, and the JavaScript for it.
+      OUTSIDE = { "A" => "^", "z" => "$", "Z" => "$", "h" => "[0-9a-fA-F]" }.freeze
+
+      # The same inside a character class, where only the hex digit means something.
+      INSIDE = { "h" => "0-9a-fA-F" }.freeze
+
+      # Characters `v` mode refuses unescaped inside a character class.
+      RESERVED = %w[( ) { } | /].freeze
+
+      # A backslash and the character it escapes.
+      ESCAPE = /\\(.)/m
+
+      # The end of a character class.
+      CLASS_END = /\]/
+
+      # @param pattern [String, nil] the attribute's pattern
+      # @return [String, nil] the pattern for an input, or nil when the attribute has none
+      def self.for(pattern) = pattern && new(pattern).to_s
+
+      # @param pattern [String] the attribute's pattern
+      def initialize(pattern)
+        @pattern = pattern
+        @depth = 0
+      end
+
+      # @return [String] the pattern, wrapped to be found anywhere in the value
+      def to_s = ".*(?:#{translated}).*"
+
+      private
+
+      def translated
+        scanner = StringScanner.new(@pattern)
+        out = +""
+        out << step(scanner) until scanner.eos?
+        out
+      end
+
+      def step(scanner)
+        return escaped(scanner[1]) if scanner.scan(ESCAPE)
+        return open_class(scanner) if scanner.scan("[")
+
+        @depth.positive? ? in_class(scanner.getch, scanner) : scanner.getch
+      end
+
+      def escaped(char)
+        (@depth.zero? ? OUTSIDE : INSIDE).fetch(char) { "\\#{char}" }
+      end
+
+      # A class opens with its negation and a leading `-` read as the literals they are.
+      def open_class(scanner)
+        @depth += 1
+        opened = +"["
+        opened << "^" if scanner.scan("^")
+        opened << "\\-" if scanner.scan("-")
+        opened
+      end
+
+      def in_class(char, scanner)
+        @depth -= 1 if char == "]"
+        return "\\-" if char == "-" && scanner.check(CLASS_END)
+
+        RESERVED.include?(char) ? "\\#{char}" : char
+      end
+    end
+  end
+end

data/lib/hecks/forms/index_renderer.rb

@@ -3,32 +3,32 @@ require_relative "field_shape"
 
 module Hecks
   module Forms
-    # The home page: every exposed chapter and the aggregates on it.
+    # The home page: every exposed bluebook and the aggregates on it.
     module IndexRenderer
-      # Renders the home page body: one section per exposed chapter, each linking to its
+      # Renders the home page body: one section per exposed bluebook, each linking to its
       # aggregates.
       #
-      # @param chapters [Hash{String => Bluebook::Chapter}] the loaded chapters by domain
+      # @param bluebooks [Hash{String => Bluebook::Declaration}] the loaded bluebooks by domain
       #   name, in `expose` order
-      # @return [String] the HTML page body; only the heading when `chapters` is empty
-      def self.render(chapters)
-        sections = chapters.map { |name, chapter| chapter_section(name, chapter) }
+      # @return [String] the HTML page body; only the heading when `bluebooks` is empty
+      def self.render(declarations)
+        sections = declarations.map { |name, declaration| bluebook_section(name, declaration) }
         <<~HTML
           <h1>Exposed domains</h1>
           #{sections.join}
         HTML
       end
 
-      # Renders one chapter's section: its name, its vision as a badge when it declares one,
+      # Renders one bluebook's section: its name, its vision as a badge when it declares one,
       # and a link per aggregate showing how many commands and queries it has.
       #
       # @param name [String] the domain name, used as the heading and the first path segment
-      # @param chapter [Bluebook::Chapter] the loaded chapter
+      # @param bluebook [Bluebook::Declaration] the loaded bluebook
       # @return [String] HTML for the section's heading and aggregate list
-      def self.chapter_section(name, chapter)
-        items = chapter.aggregates.map { |aggregate| aggregate_item(name, aggregate) }
+      def self.bluebook_section(name, declaration)
+        items = declaration.aggregates.map { |aggregate| aggregate_item(name, aggregate) }
         <<~HTML
-          <h2>#{Escape.html(name)}#{%( <span class="badge">#{Escape.html(chapter.vision)}</span>) if chapter.vision}</h2>
+          <h2>#{Escape.html(name)}#{%( <span class="badge">#{Escape.html(declaration.vision)}</span>) if declaration.vision}</h2>
           <ul class="verb-list">#{items.join}</ul>
         HTML
       end

data/lib/hecks/forms/params.rb

@@ -108,7 +108,8 @@ module Hecks
         return SKIP if text.nil? || text.strip.empty?
 
         item = field.children.first
-        text.each_line.map(&:strip).reject(&:empty?).map do |line|
+        lines = text.each_line.map(&:strip).reject(&:empty?)
+        lines.map do |line|
           item.leaf? ? cast_scalar(item, line) : JSON.parse(line, symbolize_names: true)
         end
       end

data/lib/hecks/forms/port_argument.rb

@@ -3,6 +3,9 @@ module Hecks
     # Reads hecks present's `-p PORT` / `--port PORT` / `--port=PORT` argument.
     # Returns `[port, nil]` or `[nil, message]`; a non-numeric port is refused, not read as 0.
     module PortArgument
+      # A whole number written in digits alone.
+      WHOLE_NUMBER = /\A\d+\z/
+
       module_function
 
       # Reads the `-p`/`--port` argument out of an argv array.
@@ -29,7 +32,7 @@ module Hecks
       #   is a whole number between 1 and 65535, or `[nil, message]` otherwise
       def resolve(value)
         return [nil, "-p/--port requires a value"] if value.nil? || value.empty?
-        return [nil, "-p/--port must be a whole number, got #{value.inspect}"] unless value.match?(/\A\d+\z/)
+        return [nil, "-p/--port must be a whole number, got #{value.inspect}"] unless value.match?(WHOLE_NUMBER)
 
         port = value.to_i
         return [nil, "-p/--port must be between 1 and 65535, got #{port}"] unless (1..65_535).cover?(port)

data/lib/hecks/forms/query_form_renderer.rb

@@ -81,7 +81,7 @@ module Hecks
       def self.error_banner(error)
         return "" unless error
 
-        kind = Escape.html(error.class.name.split("::").last)
+        kind = Escape.html(Naming.demodulise(error.class.name))
         %(<div class="error-banner" role="alert"><p><strong>Refused (#{kind}):</strong> ) \
           "#{Escape.html(error.message)}</p></div>"
       end

data/lib/hecks/forms/record_renderer.rb

@@ -38,7 +38,7 @@ module Hecks
         return nil unless instance
 
         state = instance.state
-        current = aggregate.lifecycle && state[aggregate.lifecycle.field]
+        current = aggregate.lifecycle && state[aggregate.lifecycle_field]
         <<~HTML
           <h1>#{Escape.html(Humanize.phrase(aggregate.hecks_name))} <span class="mono">#{Escape.html(id)}</span></h1>
           #{lifecycle_badge(aggregate, current)}
@@ -54,7 +54,7 @@ module Hecks
       def self.lifecycle_badge(aggregate, current)
         return unless current
 
-        %(<span class="badge role">#{Escape.html(aggregate.lifecycle.field)}: #{Escape.html(current)}</span>)
+        %(<span class="badge role">#{Escape.html(aggregate.lifecycle_field)}: #{Escape.html(current)}</span>)
       end
 
       def self.state_table(state)

data/lib/hecks/forms/record_table.rb

@@ -11,7 +11,7 @@ module Hecks
     module RecordTable
       # Identity, lifecycle state, then scalar attributes, capped at seven columns.
       def self.columns(aggregate)
-        lifecycle = aggregate.lifecycle&.field
+        lifecycle = aggregate.lifecycle_field
         scalars = aggregate.attributes.reject { |a| a.reference? || a.list? }.map(&:name)
         [*aggregate.identity_heads, lifecycle, *scalars].compact.uniq.first(7)
       end

data/lib/hecks/forms/reference_options.rb

@@ -18,7 +18,8 @@ module Hecks
       end
 
       def self.options_for(registry, domain, aggregate)
-        registry.repository(domain, aggregate).all.first(200).map { |instance| [instance.id, instance.id] }
+        records = registry.repository(domain, aggregate).all.first(200)
+        records.map { |instance| [instance.id, instance.id] }
       rescue StandardError
         nil # a wiring gap (no repository bound) degrades to a plain text id input, not a 500
       end

data/lib/hecks/forms/text_shape.rb

@@ -17,6 +17,9 @@ module Hecks
         TEL_HINT      = HINTS.fetch("tel")
         TEXTAREA_HINT = HINTS.fetch("textarea")
 
+        # A web scheme anywhere in a pattern, any case: the pattern asks for a URL.
+        WEB_SCHEME = /https?/i
+
         # @param attribute [Bluebook::Attribute] a string-typed attribute
         # @param common [Hash] the field attributes every kind shares
         # @return [Forms::Field] a `:text` field, or a `:textarea` for a long-form name
@@ -29,7 +32,7 @@ module Hecks
 
         def self.html_type(name, pattern)
           return "email" if pattern.include?("@") || name.match?(EMAIL_HINT)
-          return "url" if pattern.match?(/https?/i) || name.match?(URL_HINT)
+          return "url" if pattern.match?(WEB_SCHEME) || name.match?(URL_HINT)
           return "tel" if name.match?(TEL_HINT)
 
           "text"

data/lib/hecks/forms/value_object_shape.rb

@@ -2,7 +2,7 @@ module Hecks
   module Forms
     # Shared value-object shape classification, so callers such as
     # field_shape.rb and sql_query_builder.rb agree on it. There is no Ruby ui_schema; the Rust
-    # host builds the UI schema (rust/host/src/ui_schema.rs) from the same field-shape rules.
+    # host builds the UI schema (rust/host/core/src/ui_schema.rs) from the same field-shape rules.
     module ValueObjectShape
       module_function
 

data/lib/hecks/forms.rb

@@ -6,8 +6,8 @@ require_relative "forms/app"
 module Hecks
   # Per-app `expose` configuration, looked up by the Rack app at request time.
   module Forms
-    # The chapters one app exposes. Plain module state, outside `syntax.bluebook` and
-    # the registry; one `expose` switches on a whole chapter, not a single command or query.
+    # The bluebooks one app exposes. Plain module state, outside `syntax.bluebook` and
+    # the registry; one `expose` switches on a whole bluebook, not a single command or query.
     class Config
       attr_reader :name, :exposes
 
@@ -18,16 +18,16 @@ module Hecks
         @exposes = []
       end
 
-      # Switches on the forms of one whole chapter for this app; called inside the
+      # Switches on the forms of one whole bluebook for this app; called inside the
       # `Forms.configure` block.
       #
-      # @param chapter_name [String, Symbol] name of the chapter (domain) to expose, such as
+      # @param declaration_name [String, Symbol] name of the bluebook (domain) to expose, such as
       #   `"Banking"`; stored as a String
-      # @return [Array<String>] every chapter name exposed so far, in declaration order
-      def expose(chapter_name) = @exposes << chapter_name.to_s
+      # @return [Array<String>] every bluebook name exposed so far, in declaration order
+      def expose(declaration_name) = @exposes << declaration_name.to_s
     end
 
-    # Declares an app and the chapters it exposes, replacing any earlier configuration
+    # Declares an app and the bluebooks it exposes, replacing any earlier configuration
     # registered under the same name.
     #
     # @param name [String, Symbol] the app name `App.for` later looks the configuration up by

data/lib/hecks/fqn.rb

@@ -6,6 +6,12 @@ module Hecks
   class Fqn
     class Invalid < ArgumentError; end
 
+    # A PascalCase command verb.
+    COMMAND_VERB = /\A[A-Z][A-Za-z0-9]*\z/
+
+    # A snake_case query verb.
+    QUERY_VERB = /\A[a-z][a-z0-9_]*\z/
+
     attr_reader :realm, :domain, :version, :aggregate, :verb, :kind
 
     # Builds the FQN of one command on an aggregate.
@@ -100,13 +106,13 @@ module Hecks
     #
     # @param name [String, Symbol, #to_s] the candidate verb
     # @return [Boolean] true if `name` matches the PascalCase command shape
-    def self.command_name?(name) = /\A[A-Z][A-Za-z0-9]*\z/.match?(name.to_s)
+    def self.command_name?(name) = COMMAND_VERB.match?(name.to_s)
 
     # Whether `name` is a valid query verb: snake_case.
     #
     # @param name [String, Symbol, #to_s] the candidate verb
     # @return [Boolean] true if `name` matches the snake_case query shape
-    def self.query_name?(name)   = /\A[a-z][a-z0-9_]*\z/.match?(name.to_s)
+    def self.query_name?(name)   = QUERY_VERB.match?(name.to_s)
 
     # @param realm [String, nil] deployment identity from the world, or nil for an
     #   unrealmed address

data/lib/hecks/framework/bluebook/change.bluebook

@@ -4,7 +4,7 @@ Hecks.bluebook "Change" do
 
   # A framework member like Governance and Identity: attach it with `attaches "Change"` in the
   # consuming domain's own `.hecksagon`. The script is the port's adapter, so what a change
-  # does lives behind the `Script` port, and this chapter holds only how any change moves.
+  # does lives behind the `Script` port, and this bluebook holds only how any change moves.
   aggregate "Change" do
     description "One change a script makes, previewed before it is carried out and applied only if its plan is unchanged."
 
@@ -54,19 +54,17 @@ Hecks.bluebook "Change" do
       transition "Confirm"  => "confirmed", from: "planned"
       transition "Complete" => "applied",   from: "confirmed"
       transition "Fault"    => "faulted",   from: ["requested", "planned", "confirmed"]
+      mark :terminal, "applied", "faulted"
     end
 
     command "Request" do
       role "Maintainer"
       goal "Ask for a change by naming its script and giving the script's arguments"
 
-      attribute :run,       RunKey
-      attribute :script,    ScriptName
-      attribute :arguments, list_of(Argument), optional: true
+      attribute :run,       RunKey, sets: true
+      attribute :script,    ScriptName, sets: true
+      attribute :arguments, list_of(Argument), optional: true, sets: true
 
-      sets :run
-      sets :script
-      sets :arguments
 
       emits ChangeRequested
     end
@@ -76,10 +74,9 @@ Hecks.bluebook "Change" do
       goal "Record what the script would do, and the digest that stands for it"
 
       reference_to Change
-      attribute :plan,   Report
+      attribute :plan,   Report, sets: true
       attribute :digest, Digest
 
-      sets :plan
       sets :planned_digest, to: :digest
 
       emits ChangePlanned
@@ -102,9 +99,8 @@ Hecks.bluebook "Change" do
       goal "Record that the confirmed plan was carried out, and what the script reported"
 
       reference_to Change
-      attribute :report, Report
+      attribute :report, Report, sets: true
 
-      sets :report
 
       emits ChangeApplied
     end
@@ -114,9 +110,8 @@ Hecks.bluebook "Change" do
       goal "Record that the change was refused or could not be carried out, and why"
 
       reference_to Change
-      attribute :refusal, Report
+      attribute :refusal, Report, sets: true
 
-      sets :refusal
 
       emits ChangeFaulted
     end
@@ -137,7 +132,7 @@ Hecks.bluebook "Change" do
 
   policy "ExamineWhenRequested" do
     on      "Change.ChangeRequested"
-    trigger Change::Script::Examine, with: { run: :run }
+    ask     :examine, with: { run: :run }
   end
 
   policy "RecordThePlanWhenExamined" do
@@ -147,7 +142,7 @@ Hecks.bluebook "Change" do
 
   policy "PerformWhenConfirmed" do
     on      "Change.ChangeConfirmed"
-    trigger Change::Script::Perform, with: { run: :run }
+    ask     :perform, with: { run: :run }
   end
 
   policy "RecordTheOutcomeWhenPerformed" do

data/lib/hecks/framework/bluebook/change.hecksagon

@@ -4,7 +4,7 @@ Hecks.hecksagon "Change" do
   persisted_by "Memory"
 
   # The change moves through two asks: `Examine` plans it, `Perform` carries it out. What a
-  # script does is the adapter's, so the chapter never names one.
+  # script does is the adapter's, so the bluebook never names one.
   Change::Change.port "Script" do
     asks "Examine", to: Change do
       attribute :run, RunKey