hecks 5.0.0 → 6.0.0

data/lib/hecks/doc/reference/harvester.rb

@@ -8,6 +8,9 @@ module Hecks
       # still parses unchanged. A `## ` line inside a fence is not a heading: it is a comment in
       # the runnable example, not a section break.
       class Harvester
+        # A `## word` heading line, capturing the word.
+        SECTION_HEADING = /\A## (\S+)\s*\z/
+
         def initialize
           @prose = {}
           @current = PREAMBLE
@@ -29,7 +32,7 @@ module Hecks
 
         def consume(line)
           @in_fence = !@in_fence if line.start_with?("```")
-          heading = line.match(/\A## (\S+)\s*\z/) unless @in_fence
+          heading = line.match(SECTION_HEADING) unless @in_fence
           if heading
             start_section(heading[1])
           elsif line.include?(GENERATED_END)

data/lib/hecks/doc/reference/readme.rb

@@ -4,6 +4,12 @@ module Hecks
       # README's own generated regions, keyed by region id instead of a word. Extended onto
       # `Reference`.
       module Readme
+        # The `#` that opens a Markdown heading, and the space after it.
+        HEADING_MARK = /\A#\s*/
+
+        # A `vision "..."` line, capturing the vision.
+        VISION = /vision\s+"([^"]*)"/
+
         # README's own generated regions, keyed by region id instead of a word.
         def readme_regions(root)
           {
@@ -20,16 +26,15 @@ module Hecks
                      .reject { |p| %w[AUTHORING.md].include?(File.basename(p)) }
           lines = paths.map do |path|
             heading = File.foreach(path).find { |line| line.start_with?("# ") }
-            title = heading ? heading.sub(/\A#\s*/, "").strip : File.basename(path)
+            title = heading ? heading.sub(HEADING_MARK, "").strip : File.basename(path)
             "- [#{title}](docs/implemented/guides/#{File.basename(path)})"
           end
           lines.join("\n")
         end
 
-        # Links the reference index, with its context count.
+        # Links the reference index.
         def reference_index(_root)
-          count = contexts.size
-          "[The DSL reference](docs/implemented/reference/index.md) — #{count} contexts, generated from " \
+          "[The DSL reference](docs/implemented/reference/index.md) — generated from " \
             "the aggregate-local tables under `lib/hecks/language/` and held to them by " \
             "`spec/reference_golden_spec.rb`."
         end
@@ -39,7 +44,7 @@ module Hecks
         def diagram_showcase(root)
           lifecycle = File.read(File.join(root, "docs/generated/diagrams/pizzas/Order_lifecycle.mmd")).strip
           <<~MARKDOWN.strip
-            `hecks project_diagrams` reads a booted domain's own declaration and draws it as Mermaid — nine kinds so far: `<Name>_lifecycle.mmd`, `relationships.mmd`, `dispatch.mmd`, `roles.mmd`, `ports.mmd`, `read_models.mmd`, `<Name>_surface.mmd` (what a command does, and what it writes), `<Name>_saga.mmd`, and `frameworks.mmd`. Nothing hand-drawn — the same reason a domain is data at all. Order's own lifecycle, straight off the bluebook above:
+            `hecks project_diagrams` reads a booted domain's own declaration and draws it as Mermaid — `<Name>_lifecycle.mmd`, `relationships.mmd`, `dispatch.mmd`, `roles.mmd`, `ports.mmd`, `read_models.mmd`, `<Name>_surface.mmd` (what a command does, and what it writes), `<Name>_saga.mmd`, and `frameworks.mmd`. Nothing hand-drawn — the same reason a domain is data at all. Order's own lifecycle, straight off the bluebook above:
 
             ```mermaid
             #{lifecycle}
@@ -59,7 +64,7 @@ module Hecks
           bluebooks = example_bluebooks(dir)
           return if bluebooks.empty?
 
-          vision = bluebooks.filter_map { |bluebook| File.read(bluebook)[/vision\s+"([^"]*)"/, 1] }.first
+          vision = bluebooks.filter_map { |bluebook| File.read(bluebook)[VISION, 1] }.first
           "- **#{File.basename(dir.chomp("/"))}** — #{vision}"
         end
 

data/lib/hecks/doc/reference/rendering.rb

@@ -111,11 +111,14 @@ module Hecks
               .map { |arg| arg[:fills].to_s.empty? ? arg[:kind] : arg[:fills] }
         end
 
-        # @return [Array<String>] the named arguments, as `name:`
+        # @return [Array<String>] the named arguments, as `name:`; an open row reads `key:`
         def named_parts(args)
-          args.select { |arg| arg[:at].to_s.empty? }.map { |arg| "#{arg[:named]}:" }
+          args.select { |arg| arg[:at].to_s.empty? }.map { |arg| "#{named_label(arg)}:" }
         end
 
+        # A named argument's name, or `key` for an open row that takes any name.
+        def named_label(arg) = arg[:named].to_s.empty? ? "key" : arg[:named]
+
         # Renders one word's arguments as a Markdown table, or "" if it declares none.
         def argument_table(row)
           args = word_arguments(row)
@@ -123,23 +126,26 @@ module Hecks
 
           lines = ["", "| argument | kind | required | fills |", "|---|---|---|---|"]
           args.each do |arg|
-            name = arg[:at].to_s.empty? ? "`#{arg[:named]}:`" : "positional #{arg[:at]}"
+            name = arg[:at].to_s.empty? ? "`#{named_label(arg)}:`" : "positional #{arg[:at]}"
             lines << "| #{name} | #{arg[:kind]} | #{arg[:required]} | #{arg[:fills]} |"
           end
           "#{lines.join("\n")}\n"
         end
 
+        # Every word row of a context, repeats included.
+        def context_words(context) = keywords.select { |row| row[:context] == context }.map { |row| row[:word] }
+
         # Renders the reference index page, one linked entry per context.
         def render_index
           listed = contexts.map do |context|
-            count = keywords.select { |row| row[:context] == context }.map { |row| row[:word] }.uniq.size
+            count = context_words(context).uniq.size
             "- [#{context}](#{page_name(context)}) — #{count} #{count == 1 ? "word" : "words"}"
           end
           <<~INDEX
             # The DSL reference
 
             One page per context — the place in a file where a word may be
-            typed. Generated by `hecks language_run.project_reference` from the Syntax chapter;
+            typed. Generated by `hecks language_run.project_reference` from the Syntax declaration;
             the prose between the generated markers is hand-written and
             survives regeneration.
 

data/lib/hecks/doc/reference.rb

@@ -8,7 +8,7 @@ require_relative "reference/rendering"
 
 module Hecks
   module Doc
-    # The DSL reference, projected from the language's own Syntax chapter so
+    # The DSL reference, projected from the language's own Syntax bluebook so
     # its tables can never drift from the live builders. Regenerate with
     # `hecks language_run.project_reference`.
     #
@@ -19,7 +19,7 @@ module Hecks
       TODO_SENTINEL = "<!-- TODO: document this word -->".freeze
 
       # A page's hand-written opening, keyed under a Symbol so it can never
-      # collide with a word (words are always Strings off the Syntax chapter).
+      # collide with a word (words are always Strings off the Syntax bluebook).
       PREAMBLE = :preamble
 
       extend Readme
@@ -35,7 +35,7 @@ module Hecks
       # parts of a page not about one word (a lede, README's indexes).
       def region_begin(id) = "<!-- generated:begin id=#{id} -->"
 
-      # The language's own Syntax aggregate, read off the judged grammar chapter.
+      # The language's own Syntax aggregate, read off the judged grammar bluebook.
       def syntax
         meta = Bluebook::MetaValidator.grammar_registry.bluebook("Bluebook")
         meta.aggregates.find { |aggregate| aggregate.hecks_name == "Syntax" }
@@ -44,10 +44,12 @@ module Hecks
       # Reads one closed-set value object's declared members off the Syntax
       # aggregate, as string-valued Hashes.
       def rows(name)
-        syntax.value_objects.find { |vo| vo.hecks_name == name }
-              .members.map { |row| row.to_h.transform_values(&:to_s) }
+        syntax_value_object(name).members.map { |row| row.to_h.transform_values(&:to_s) }
       end
 
+      # The Syntax aggregate's value object of that name.
+      def syntax_value_object(name) = syntax.value_objects.find { |vo| vo.hecks_name == name }
+
       # Delegates to SyntaxBoot.call's own cache instead of memoizing here —
       # a second cache could lock in a stale set with no way to invalidate (ADR 0026).
       def keywords  = Bluebook::MetaValidator::SyntaxBoot.call[:keywords]

data/lib/hecks/embryonaut_bluebook/lock.rb

@@ -5,9 +5,13 @@ module Hecks
     # The digest here must match the source repo's own bin/bluebook_digest
     # output for the same tag, or a vendored copy cannot be trusted.
     Lock = Struct.new(:package, :version, :tag, :commit, :digest, :shape, keyword_init: true) do
+      # What a package's `bluebook/` directory ships and a project vendors: its bluebooks, and the
+      # plugin adapters and wasm modules that answer their queries.
+      self::PACKAGE_FILES = "*.{bluebook,adapter,wasm}".freeze
+
       # Sorted by name so the digest never depends on directory listing order.
       def self.digest_of(dir)
-        names = Dir.children(dir).select { |name| name.end_with?(".bluebook") }.sort
+        names = Dir.children(dir).select { |name| File.fnmatch(self::PACKAGE_FILES, name, File::FNM_EXTGLOB) }.sort
         return nil if names.empty?
 
         lines = names.map { |name| "#{Digest::SHA256.file(File.join(dir, name)).hexdigest}  #{name}\n" }

data/lib/hecks/embryonaut_bluebook/manifest.rb

@@ -80,7 +80,13 @@ module Hecks
 
         lock = Lock.read(path)
         judge(name, dir, lock, problems)
-        lock.to_h.transform_keys(&:to_s).slice(*ENTRY).merge("shape" => Array(lock.shape))
+        entry_fields(lock)
+      end
+
+      # The lock's fields a manifest entry records, with its shape as a list.
+      def entry_fields(lock)
+        recorded = lock.to_h.transform_keys(&:to_s)
+        recorded.slice(*ENTRY).merge("shape" => Array(lock.shape))
       end
 
       def judge(name, dir, lock, problems)

data/lib/hecks/embryonaut_bluebook/registry/changelog.rb

@@ -4,6 +4,9 @@ module Hecks
       # A package's `CHANGELOG.md`: whether a version has an entry, and what it says. Included in
       # `Registry`.
       module Changelog
+        # The blank lines that end a section.
+        TRAILING_NEWLINES = /\n+\z/
+
         private
 
         def changelog_entry?(package, version)
@@ -18,7 +21,7 @@ module Hecks
             on = line.match?(/^## #{Regexp.escape(version)}( |$)/) if line.start_with?("## ")
             on && !line.start_with?("## ")
           end
-          lines.join("\n").sub(/\n+\z/, "")
+          lines.join("\n").sub(TRAILING_NEWLINES, "")
         end
       end
     end

data/lib/hecks/embryonaut_bluebook/registry/versions.rb

@@ -4,11 +4,20 @@ module Hecks
       # A package's versions: the one its manifest says, the release tags it has, and which of two
       # is newer. Included in `Registry`.
       module Versions
+        # The `version:` line of a `bluebook.yml`, capturing the version.
+        VERSION_LINE = /^version: *(.*)$/
+
+        # A run of digits or a run of anything else: the parts `sort -V` compares.
+        VERSION_PART = /\d+|\D+/
+
+        # A version part that is a number.
+        NUMERIC_PART = /\A\d/
+
         private
 
         def manifest_version(package)
           file = File.join(@root, package, "bluebook.yml")
-          File.file?(file) ? File.read(file)[/^version: *(.*)$/, 1] : nil
+          File.file?(file) ? File.read(file)[VERSION_LINE, 1] : nil
         end
 
         def tags(package) = @source.tags("#{package}-v*")
@@ -20,7 +29,9 @@ module Hecks
         # The greater of two versions, compared as `sort -V` does: runs of digits as numbers.
         def newest(left, right) = [left, right].max_by { |version| order(version) }
 
-        def order(version) = version.scan(/\d+|\D+/).map { |part| part.match?(/\A\d/) ? [0, part.to_i, ""] : [1, 0, part] }
+        def order(version)
+          version.scan(VERSION_PART).map { |part| part.match?(NUMERIC_PART) ? [0, part.to_i, ""] : [1, 0, part] }
+        end
       end
     end
   end

data/lib/hecks/embryonaut_bluebook/registry.rb

@@ -25,6 +25,9 @@ module Hecks
       # A package name is a directory name.
       NAME = /\A[a-z][a-z0-9_]*\z/
 
+      # The `name:` line of a `bluebook.yml`, capturing the name.
+      NAME_LINE = /^name: *(.*)$/
+
       # What `check` found, in package order: a note for a package that has no release yet and a
       # sentence for each fault.
       class Report
@@ -133,12 +136,12 @@ module Hecks
       end
 
       def check_name(package, report)
-        name = File.read(File.join(@root, package, "bluebook.yml"))[/^name: *(.*)$/, 1]
+        name = File.read(File.join(@root, package, "bluebook.yml"))[NAME_LINE, 1]
         report.fault "#{package}: bluebook.yml name does not match the directory" unless name == package
       end
 
       def check_tag(package, tag, report)
-        tagged = @source.read(tag, "#{package}/bluebook.yml").to_s[/^version: *(.*)$/, 1].to_s
+        tagged = @source.read(tag, "#{package}/bluebook.yml").to_s[VERSION_LINE, 1].to_s
         return if tagged == tag.delete_prefix("#{package}-v")
 
         report.fault "#{package}: #{tag} points at a commit whose bluebook.yml says '#{tagged}'"

data/lib/hecks/embryonaut_bluebook/shape.rb

@@ -24,7 +24,7 @@ module Hecks
         end
         scratch
       rescue StandardError, ScriptError => e
-        raise Vendoring::Error, "the bluebook files do not load: #{e.class}: #{e.message.lines.first.to_s.strip}"
+        raise Vendoring::Error, "the bluebook files do not load: #{e.class}: #{Text.first_line(e.message)}"
       end
     end
   end

data/lib/hecks/embryonaut_bluebook/vendor.rb

@@ -17,6 +17,9 @@ module Hecks
       # A package name is a directory name and a bluebook name stem.
       NAME = /\A[a-z][a-z0-9_]*\z/
 
+      # The `version:` line of a `bluebook.yml`, capturing the version.
+      VERSION_LINE = /^version: *(\S+)/
+
       # What a vendoring changed; previous_version/previous_shape are nil when
       # there was no earlier vendored copy.
       Result = Struct.new(:package, :commit, :version, :tag, :digest, :shape,
@@ -57,7 +60,7 @@ module Hecks
       def pin_files(tag, version, previous)
         shape = nil
         pin = Vendoring.pin(from: @source.path, ref: tag || @ref, subtree: "#{@name}/bluebook",
-                            into: package_dir, glob: "*.bluebook") do |staged, commit|
+                            into: package_dir, glob: Lock::PACKAGE_FILES) do |staged, commit|
           shape = Shape.labels(staged)
           next nil unless tag
 
@@ -74,7 +77,7 @@ module Hecks
         return nil unless tag
 
         version = tag.delete_prefix("#{@name}-v")
-        tagged = @source.read(tag, "#{@name}/bluebook.yml")&.[](/^version: *(\S+)/, 1)
+        tagged = @source.read(tag, "#{@name}/bluebook.yml")&.[](VERSION_LINE, 1)
         unless tagged == version
           raise Vendoring::Error, "#{tag} points at a commit whose bluebook.yml says version #{tagged.inspect}"
         end

data/lib/hecks/embryonaut_bluebook/vendor_cli.rb

@@ -10,6 +10,20 @@ module Hecks
     module VendorCli
       USAGE = "usage: vendor_bluebook <package>[@<version-or-commit>] [--from PATH] [--root PATH]".freeze
 
+      # The registry checkout a package is vendored from when `--from` does not name one:
+      # `EMBRYONAUT_BLUEBOOKS_SRC` when set, else an `embryonaut_bluebooks` checkout beside the
+      # project (its parent directory), which is where the registry is cloned.
+      #
+      # @param root [String] the project the package is vendored into
+      # @param env [Hash{String => String}] the environment
+      # @return [String, nil] the registry checkout, nil when there is none to find
+      def self.default_source(root, env = ENV)
+        return env["EMBRYONAUT_BLUEBOOKS_SRC"] if env["EMBRYONAUT_BLUEBOOKS_SRC"]
+
+        beside = File.join(File.dirname(File.expand_path(root)), "embryonaut_bluebooks")
+        beside if File.directory?(beside)
+      end
+
       # Runs the command and reports on the given streams.
       #
       # @param argv [Array<String>] the command-line arguments
@@ -19,7 +33,7 @@ module Hecks
       # @param root [String] the default project root
       # @return [Integer] the exit status, 0 when the package was vendored
       def self.run(argv, env: ENV, out: $stdout, err: $stderr, root: Dir.pwd)
-        options = { from: env["EMBRYONAUT_BLUEBOOKS_SRC"], root: root }
+        options = { from: default_source(root, env), root: root }
         spec = parse(argv, options)
         return usage(err) unless spec && options[:from]
 

data/lib/hecks/embryonaut_bluebook.rb

@@ -20,26 +20,40 @@ module Hecks
     #   as `"payments"`
     # @param registry [Runtime::Registry, nil] the registry to vendor into and
     #   check for an existing load; defaults to the current boot registry
-    # @return [void]
+    # @return [String] the bluebook the package's bluebook declares (`"Documents"` for the
+    #   `document` package), its directory name in Pascal case when no file declares one
     # @raise [Runtime::WiringError] if `registry` has no root, or no vendored
     #   package named `name` is checked out
     def self.load!(name, registry: Hecks.current_registry)
       check_loadable!(name, registry)
-      return if registry.bluebook(Naming.pascal(name.to_s))
-
-      dir   = File.join(registry.root, "vendor", "embryonaut_bluebooks", name.to_s, "bluebook")
-      files = Dir.glob(File.join(dir, "*.bluebook"))
-
-      if files.empty?
-        raise Runtime::WiringError,
-              "no vendored embryonaut bluebook named #{name.inspect} at #{dir} — " \
-              "vendor it with hecks vendor #{name}"
-      end
-
+      dir = File.join(registry.root, "vendor", "embryonaut_bluebooks", name.to_s, "bluebook")
       # Loaded in the glob's alphabetical order; a package with several
       # files that reopen the same bluebook is named to rely on that.
+      files = vendored_bluebooks(name, dir)
+      declaration = FrameworkBluebooks.declaration_name(files.first) || Naming.pascal(name.to_s)
+      load_package(files, dir) unless registry.bluebook(declaration)
+      declaration
+    end
+
+    # Loads the package's bluebooks, then its plugin adapters, which answer its queries with the
+    # wasm modules beside them.
+    def self.load_package(files, dir)
       files.each { |file| Kernel.load(file) }
+      Dir.glob(File.join(dir, "*.adapter")).each { |file| Kernel.load(file) }
+    end
+    private_class_method :load_package
+
+    # @return [Array<String>] the package's vendored `.bluebook` files
+    # @raise [Runtime::WiringError] if there are none
+    def self.vendored_bluebooks(name, dir)
+      files = Dir.glob(File.join(dir, "*.bluebook"))
+      return files unless files.empty?
+
+      raise Runtime::WiringError,
+            "no vendored embryonaut bluebook named #{name.inspect} at #{dir} — " \
+            "vendor it with hecks vendor #{name}"
     end
+    private_class_method :vendored_bluebooks
 
     # @raise [Runtime::WiringError] if `registry` has no root to vendor from, or `name` is not a
     #   package name

data/lib/hecks/engine_agreement.rb

@@ -32,6 +32,9 @@ module Hecks
     #   @return [Array<String>] each disagreement, in words; empty when the engines agree
     Finding = Struct.new(:declared, :problems)
 
+    # An `it "..."` or `describe "..."` description that names `eq` as a word.
+    EQ_DESCRIPTION = /\b(?:it|describe)\s+"[^"]*\beq\b[^"]*"/i
+
     module_function
 
     # Checks the engines against the vocabulary.
@@ -140,7 +143,7 @@ module Hecks
       # counts; no other comparator gets that leniency.
       return false unless comparator == "eq"
 
-      /\b(?:it|describe)\s+"[^"]*\beq\b[^"]*"/i.match?(text) || false
+      EQ_DESCRIPTION.match?(text) || false
     end
 
     # @param finding [Finding] what a check found

data/lib/hecks/forms/app/commands.rb

@@ -3,6 +3,7 @@ require_relative "../command_form_renderer"
 require_relative "../params"
 require_relative "../../adapters/driving/command_request"
 require_relative "../../adapters/driving/json"
+require_relative "../../projections/command_schema"
 
 module Hecks
   module Forms
@@ -11,6 +12,9 @@ module Hecks
       # same
       # dispatch.
       module Commands
+        # The values of `dry_run=` / `X-Dry-Run:` that ask for a validation instead of a dispatch.
+        DRY_RUN_FLAGS = %w[1 true].freeze
+
         private
 
         def command_route(request, domain, aggregate, command, format)
@@ -45,14 +49,42 @@ module Hecks
         end
 
         def command_json(request, domain, aggregate, command)
-          return json(200, command.to_h) if request.get? && request.GET.except("format").empty?
+          return command_read_json(request, domain, aggregate, command) if request.get?
           return respond(405, "text/plain", "GET or POST only") unless request.post?
+          return validated_json(request, domain, aggregate, command) if dry_run_requested?(request)
 
           created_json(request, domain, aggregate, command)
         rescue *Runtime::DOMAIN_REFUSALS, ArgumentError, TypeError, JSON::ParserError => e
           refusal_json(e, refusal_status(e))
         end
 
+        # A GET of a command's JSON route: its descriptor, or with `?schema=1` its JSON Schema.
+        def command_read_json(request, domain, aggregate, command)
+          return command_schema(domain, aggregate, command) if request.GET["schema"] == "1"
+          return json(200, command.to_h) if request.GET.except("format").empty?
+
+          respond(405, "text/plain", "GET or POST only")
+        end
+
+        # The JSON Schema of the facts the command takes (`?schema=1`), with the rules a schema
+        # cannot hold as `x-` annotations.
+        def command_schema(domain, aggregate, command)
+          path = "#{aggregate.hecks_name}/#{command.hecks_name}"
+          json(200, Projections::CommandSchema.document(@registry.bluebook(domain), aggregate, path, command))
+        end
+
+        # Whether the request asks to be validated, not carried out: `?dry_run=1` or `X-Dry-Run: 1`.
+        def dry_run_requested?(request)
+          DRY_RUN_FLAGS.include?(request.GET["dry_run"].to_s) || DRY_RUN_FLAGS.include?(request.get_header("HTTP_X_DRY_RUN").to_s)
+        end
+
+        # The same body, caller and route as the real command, answered as every reason it would be
+        # refused. A completed validation is a 200 whether or not it refused.
+        def validated_json(request, domain, aggregate, command)
+          _, envelope = submitted_command(request, aggregate, command)
+          json(200, @dispatcher.validate(verb_name(domain, aggregate, command), envelope).to_h)
+        end
+
         def created_json(request, domain, aggregate, command)
           _, envelope = submitted_command(request, aggregate, command)
           result = @dispatcher.dispatch_flat(verb_name(domain, aggregate, command), envelope)
@@ -78,7 +110,8 @@ module Hecks
         end
 
         def submitted_json(request, command)
-          raw = Adapters::Driving::Json.parse(request.body.read)
+          body = request.body
+          raw = Adapters::Driving::Json.parse(body.read)
           envelope = Adapters::Driving::Json.command_request(raw, receiver:        command_receiver(command),
                                                                   legacy_receiver: :id)
           [raw, envelope]

data/lib/hecks/forms/app/records.rb

@@ -7,25 +7,25 @@ module Hecks
       module Records
         private
 
-        def aggregate_route(request, chapter, aggregate_name, format)
-          aggregate = find_aggregate(chapter, aggregate_name)
+        def aggregate_route(request, declaration, aggregate_name, format)
+          aggregate = find_aggregate(declaration, aggregate_name)
           return respond(405, "text/plain", "GET only") unless request.get?
-          return aggregate_json(chapter, aggregate) unless format == "html"
+          return aggregate_json(declaration, aggregate) unless format == "html"
 
           html(Naming.plural(Humanize.phrase(aggregate.hecks_name)),
-               RecordRenderer.index(registry: @registry, domain: chapter.name, aggregate: aggregate),
-               breadcrumbs: [[chapter.name, "/"], [Humanize.phrase(aggregate.hecks_name), nil]])
+               RecordRenderer.index(registry: @registry, domain: declaration.name, aggregate: aggregate),
+               breadcrumbs: [[declaration.name, "/"], [Humanize.phrase(aggregate.hecks_name), nil]])
         end
 
-        def aggregate_json(chapter, aggregate)
-          instances = @registry.repository(chapter.name, aggregate).all
+        def aggregate_json(declaration, aggregate)
+          instances = @registry.repository(declaration.name, aggregate).all
           # `id:` is merged last so an attribute named `id` in the state cannot clobber it.
           json(200, instances.map { |i| i.state.merge(id: i.id) })
         end
 
-        def verb_or_record_route(request, chapter, aggregate_name, verb_or_id, format)
-          aggregate = find_aggregate(chapter, aggregate_name)
-          domain = chapter.name
+        def verb_or_record_route(request, declaration, aggregate_name, verb_or_id, format)
+          aggregate = find_aggregate(declaration, aggregate_name)
+          domain = declaration.name
 
           # A record id is free-form and can equal a verb name ("Close"), so a GET checks for
           # a record first. POST never views a record, so it matches the verb first.
@@ -70,8 +70,8 @@ module Hecks
           aggregate_crumbs(domain, aggregate) + [[Humanize.phrase(verb.hecks_name), nil]]
         end
 
-        def find_aggregate(chapter, name)
-          chapter.aggregate(name) || raise(RouteNotFound, "#{chapter.name} has no aggregate #{name.inspect}")
+        def find_aggregate(declaration, name)
+          declaration.aggregate(name) || raise(RouteNotFound, "#{declaration.name} has no aggregate #{name.inspect}")
         end
       end
     end

data/lib/hecks/forms/app/responses.rb

@@ -31,7 +31,7 @@ module Hecks
         def refusal_status(error) = error.is_a?(Runtime::NotFound) ? 404 : 422
 
         def refusal_json(error, status)
-          json(status, { error: error.class.name.split("::").last, message: error.message })
+          json(status, { error: Naming.demodulise(error.class.name), message: error.message })
         end
 
         def not_found(aggregate, id, format)

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