hecks 5.0.0 → 6.0.0

data/lib/hecks/cli/project_glossary.rb

@@ -2,7 +2,7 @@ require_relative "../../hecks"
 
 module Hecks
   module CLI
-    # The command behind `hecks glossary`: boots a domain and projects one chapter into its
+    # The command behind `hecks glossary`: boots a domain and projects one bluebook into its
     # Ubiquitous Language glossary, `glossary.md` plus `html/index.html` rendered from it, in the
     # domain's own `glossary/` folder.
     #
@@ -12,18 +12,18 @@ module Hecks
     module ProjectGlossary
       module_function
 
-      # Writes the chapter's glossary and prints each file written.
+      # Writes the bluebook's glossary and prints each file written.
       #
-      # @param argv [Array<String>] the domain path, then the chapter's name
+      # @param argv [Array<String>] the domain path, then the bluebook's name
       # @param program [String] the name the usage line shows
       # @return [void]
       # @raise [SystemExit] with the usage line when an argument is missing
       def call(argv, program: "hecks glossary")
-        usage = "usage: #{program} <domain-path> <ChapterName>"
-        domain_path  = argv[0] or abort usage
-        chapter_name = argv[1] or abort usage
+        usage = "usage: #{program} <domain-path> <BluebookName>"
+        domain_path = argv[0] or abort usage
+        declaration_name = argv[1] or abort usage
 
-        written = write_glossary(File.expand_path(domain_path, Dir.pwd), chapter_name)
+        written = write_glossary(File.expand_path(domain_path, Dir.pwd), declaration_name)
 
         puts "wrote #{written.size} file(s):"
         written.each { |path| puts "  #{path}" }
@@ -31,22 +31,22 @@ module Hecks
 
       # @api private
       # @return [Array<String>] the files written under the domain's `glossary/` folder
-      def write_glossary(domain, chapter_name)
+      def write_glossary(domain, declaration_name)
         runtime = Hecks.boot(domain)
-        chapter = runtime.registry.bluebook(chapter_name)
+        declaration = runtime.bluebook(declaration_name)
 
         Projector.write(
-          Projector.call(:glossary, bluebook: chapter, options: { markings: markings_for(runtime, chapter_name) }),
+          Projector.call(:glossary, bluebook: declaration, options: { markings: markings_for(runtime, declaration_name) }),
           File.join(domain, "glossary"), as: :files
         )
       end
 
-      # The privacy markings the deployment declared for fields of one chapter.
+      # The privacy markings the deployment declared for fields of one bluebook.
       #
       # @api private
-      def markings_for(runtime, chapter_name)
-        runtime.registry.pending_privacy_markings.select do |marking|
-          marking[:domain].to_s.start_with?("#{chapter_name}::")
+      def markings_for(runtime, declaration_name)
+        runtime.pending_privacy_markings.select do |marking|
+          marking[:domain].to_s.start_with?("#{declaration_name}::")
         end
       end
     end

data/lib/hecks/cli/reference.rb

@@ -7,7 +7,7 @@ module Hecks
   module CLI
     # The command behind `hecks language_run.project_reference`: regenerates
     # `docs/implemented/reference/` from
-    # the language's Syntax chapter. Tables come from the declaration; prose is kept from the
+    # the language's Syntax bluebook. Tables come from the declaration; prose is kept from the
     # committed pages.
     module Reference
       module_function

data/lib/hecks/cli/refresh_projections.rb

@@ -22,22 +22,27 @@ module Hecks
         0
       end
 
-      # Refreshes every projection of every chapter in a booted runtime.
+      # Refreshes every projection of every bluebook in a booted runtime.
       #
       # @param runtime [Runtime] a booted domain
       # @return [Integer] how many projections were caught up
       def call(runtime)
-        refreshed = 0
-        runtime.registry.bluebooks.each do |domain, bluebook|
-          bluebook.aggregates.each do |aggregate|
-            worker = Ports::Projection.worker(runtime.registry, domain, aggregate, policy: :refresh)
-            next unless worker
-
-            worker.catch_up!
-            refreshed += 1
-          end
+        registry = runtime.registry
+        registry.bluebooks.sum do |domain, bluebook|
+          bluebook.aggregates.sum { |aggregate| refresh(registry, domain, aggregate) }
         end
-        refreshed
+      end
+
+      # Catches one aggregate's projection up, when it declares one.
+      #
+      # @api private
+      # @return [Integer] 1 when a projection was caught up, else 0
+      def refresh(registry, domain, aggregate)
+        worker = Ports::Projection.worker(registry, domain, aggregate, policy: :refresh)
+        return 0 unless worker
+
+        worker.catch_up!
+        1
       end
     end
   end

data/lib/hecks/cli/run.rb

@@ -18,6 +18,9 @@ module Hecks
     # domain only when it is a directory; otherwise the nearest enclosing one is
     # used.
     module Run
+      # Script text given inline: a JSON object, perhaps after some spaces.
+      INLINE_SCRIPT = /\A\s*\{/
+
       module_function
 
       # Runs `argv` as a verb invocation or a step list against a domain.
@@ -32,6 +35,7 @@ module Hecks
         usage = "usage: #{program} [domain] <verb [name=value …] | script.json | - | '{\"steps\":[…]}'>"
         argv = argv.dup
         domain = resolve_domain(argv, usage)
+        warn_unmatched_environment(domain)
 
         # The command-line form answers unless the first argument is script-shaped,
         # in which case the step-list form takes over.
@@ -49,6 +53,23 @@ module Hecks
         domain
       end
 
+      # A run saves what it dispatches through whatever the domain binds. `HECKS_ENVIRONMENT`
+      # only changes that for a domain with an `environments/<name>.*` overlay; for any other the
+      # boot ignores it, so `HECKS_ENVIRONMENT=memory hecks run …` would persist for real without
+      # a word. Says so on stderr, where a run's JSON report stays clean on stdout.
+      #
+      # @api private
+      def warn_unmatched_environment(domain)
+        name = ENV["HECKS_ENVIRONMENT"].to_s.strip
+        return if name.empty?
+
+        overlays = File.join(Adapters::Folder.new.bluebook_directory(domain), "environments", "#{name}.*")
+        return unless Dir[overlays].empty?
+
+        warn "[hecks] HECKS_ENVIRONMENT=#{name} has no overlay in #{File.dirname(overlays)}, " \
+             "so this run saves through the domain's own bindings"
+      end
+
       # @api private
       def run_script(domain, argv, usage)
         script = argv.first or abort usage
@@ -69,19 +90,20 @@ module Hecks
       # form's "no such script".
       def cli_form(domain, argv, program)
         runtime = Hecks.boot(domain, install_driving: false)
+        Assembly.bind_ported_runtime(runtime)
         text, status = Adapters::Driving::CliRunner.call(runtime: runtime, argv: argv, program: program)
         status.zero? ? puts(text) : abort(text)
         exit 0
       end
 
-      def script_shaped?(arg) = arg == "-" || arg.match?(/\A\s*\{/) || File.file?(arg)
+      def script_shaped?(arg) = arg == "-" || arg.match?(INLINE_SCRIPT) || File.file?(arg)
 
       # Decided by looking, because a script beginning with `{` is not a filename
       # anybody meant.
       def read_source(script)
         case script
         when "-" then $stdin.read
-        when /\A\s*\{/ then script
+        when INLINE_SCRIPT then script
         else
           File.exist?(script) ? File.read(script) : abort("no such script: #{script}")
         end
@@ -92,7 +114,7 @@ module Hecks
       def parse(source)
         JSON.parse(source)
       rescue JSON::ParserError => e
-        abort "that is not JSON: #{e.message.lines.first.strip}"
+        abort "that is not JSON: #{Text.first_line(e.message)}"
       end
 
       def execute(runtime, steps)
@@ -131,9 +153,9 @@ module Hecks
 
       # @api private
       def instances(runtime)
-        runtime.registry.bluebooks.each_with_object({}) do |(domain_name, bluebook), all|
+        runtime.bluebooks.each_with_object({}) do |(domain_name, bluebook), all|
           bluebook.aggregates.each do |aggregate|
-            runtime.registry.repository(domain_name, aggregate).all.each do |record|
+            runtime.repository(domain_name, aggregate).all.each do |record|
               all["#{domain_name}::#{aggregate.name}##{record.id}"] = record.state
             end
           end

data/lib/hecks/cli/seed_semantics_corpus.rb

@@ -82,7 +82,15 @@ module Hecks
           "instances" => roundtrip(result[:instances]),
           "events"    => without_timestamps(result[:events])
         }
-        full ? expect.merge!(conformance_expectation(result)) : expect
+        full ? expect.merge!(conformance_expectation(result)) : expect.merge(cross_domain_expectation(result))
+      end
+
+      # @api private
+      # @return [Hash{String => Array}] `cross_domain` (the policy, target verb and payload each
+      #   `across` policy delivered, in order) when the run had any, otherwise empty
+      def cross_domain_expectation(result)
+        deliveries = roundtrip(result[:cross_domain] || [])
+        deliveries.empty? ? {} : { "cross_domain" => deliveries }
       end
 
       # @api private
@@ -94,9 +102,11 @@ module Hecks
       # @api private
       # @return [Hash{String => Array}] the queries, sagas, dry runs and reactions a run froze
       def conformance_expectation(result)
-        # instances_at is Replay's per-query snapshot for the property harness, not an outcome.
-        queries = roundtrip(result[:queries].map { |q| q.except(:instances_at) })
-        { "queries" => queries }.merge(CONFORMANCE_KEYS.drop(1).to_h { |k| [k, roundtrip(result[k.to_sym])] })
+        # The query_row fields are Replay's own data for the property harness, not an outcome.
+        queries = roundtrip(result[:queries].map { |q| Hecks::Fuzzing::Nondeterministic.strip(q, :query_row) })
+        expectation = { "queries" => queries }.merge(CONFORMANCE_KEYS.drop(1).to_h { |k| [k, roundtrip(result[k.to_sym])] })
+        validations = roundtrip(result[:validations])
+        validations.empty? ? expectation : expectation.merge("validations" => validations)
       end
 
       # @api private

data/lib/hecks/cli/shape.rb

@@ -42,7 +42,7 @@ module Hecks
         registry = load_files(files)
         return labels(registry) if directory
 
-        bluebook = registry.bluebooks.values.first or raise Runtime::NotFound, "#{target} declares no bluebook"
+        bluebook = registry.first_bluebook or raise Runtime::NotFound, "#{target} declares no bluebook"
         JSON.pretty_generate(Projector.call(:shape, bluebook: bluebook))
       end
 
@@ -61,9 +61,8 @@ module Hecks
       # @param registry [Runtime::Registry] a loaded registry
       # @return [String] one `<Domain> <label>` line per bluebook, sorted by name
       def labels(registry)
-        registry.bluebooks.sort_by { |name, _| name.to_s }
-                .map { |name, bluebook| "#{name} #{Runtime::StorageShape.mint_label(bluebook)}" }
-                .join("\n")
+        sorted = registry.bluebooks.sort_by { |name, _| name.to_s }
+        sorted.map { |name, bluebook| "#{name} #{Runtime::StorageShape.mint_label(bluebook)}" }.join("\n")
       end
     end
   end

data/lib/hecks/cli/smoke_http/transport.rb

@@ -24,8 +24,9 @@ module Hecks
         end
 
         def request(req)
-          options = { use_ssl: req.uri.scheme == "https", read_timeout: 8, open_timeout: 8 }
-          Net::HTTP.start(req.uri.host, req.uri.port, **options) { |http| http.request(req) }
+          uri = req.uri
+          options = { use_ssl: uri.scheme == "https", read_timeout: 8, open_timeout: 8 }
+          Net::HTTP.start(uri.host, uri.port, **options) { |http| http.request(req) }
         end
 
         def expect_status(res, code)

data/lib/hecks/cli/statements.rb

@@ -7,24 +7,24 @@ module Hecks
     # The command behind `hecks statements`: prints a booted domain's declared facts as plain
     # English sentences, through `Projections::Statements`.
     module Statements
-      USAGE = "usage: hecks statements <domain-path> <ChapterName>"
+      USAGE = "usage: hecks statements <domain-path> <BluebookName>"
 
       module_function
 
-      # Boots the domain and prints one sentence per declared fact of the named chapter.
+      # Boots the domain and prints one sentence per declared fact of the named bluebook.
       #
-      # @param argv [Array<String>] the domain path, then the chapter's name
+      # @param argv [Array<String>] the domain path, then the bluebook's name
       # @param cwd [String] what a relative domain path resolves against
       # @param out [IO] where the sentences go
       # @return [Integer] the exit status, 0 once printed
       # @raise [SystemExit] with the usage line when an argument is missing
       def call(argv, cwd: Dir.pwd, out: $stdout)
-        domain_path, chapter_name = argv
-        abort USAGE unless domain_path && chapter_name
+        domain_path, declaration_name = argv
+        abort USAGE unless domain_path && declaration_name
 
         runtime = Hecks.boot(File.expand_path(domain_path, cwd))
-        chapter = runtime.registry.bluebook(chapter_name)
-        Hecks::Projector.call(:statements, bluebook: chapter).each { |statement| out.puts statement }
+        declaration = runtime.bluebook(declaration_name)
+        Hecks::Projector.call(:statements, bluebook: declaration).each { |statement| out.puts statement }
         0
       end
     end

data/lib/hecks/cli/stores.rb

@@ -1,5 +1,6 @@
 require "json"
 require_relative "../../hecks"
+require_relative "persistence_notice"
 
 module Hecks
   module CLI
@@ -21,19 +22,86 @@ module Hecks
           exit 1
         end
 
-        puts JSON.generate(stores_of(Hecks.boot(domain).registry))
+        registry = Hecks.boot(domain).registry
+        PersistenceNotice.announce(registry, program: program)
+        puts JSON.generate(stores_of(registry))
       end
 
       # @param registry [Runtime::Registry] a booted domain's registry
+      # @param only [String, nil] a storage name; the other aggregates' repositories are not read
       # @return [Hash{String => Hash}] each aggregate's dump, keyed by its storage name
-      def stores_of(registry)
+      def stores_of(registry, only: nil)
         registry.bluebooks.each_with_object({}) do |(name, bluebook), all|
           bluebook.aggregates.each do |aggregate|
+            next if only && aggregate.storage_name != only
+
             all[aggregate.storage_name] = data_for(registry.repository(name, aggregate))
           end
         end
       end
 
+      # Reads what was asked for: reads only the named aggregate's repository when one is named.
+      #
+      # @param registry [Runtime::Registry] a booted domain's registry
+      # @param aggregate [String, nil] a storage name; nil reads every aggregate
+      # @param record [String, nil] a record id within `aggregate`
+      # @param flat [Boolean] unwrap the value objects (see `flatten`)
+      # @return [Hash] see `narrow`
+      # @raise [Runtime::NotFound] see `narrow`
+      def read(registry, aggregate, record, flat: false)
+        document = stores_of(registry, only: aggregate)
+        narrowed = narrow(document, aggregate, record, names: stored_names(registry))
+        flat ? flatten(narrowed) : narrowed
+      end
+
+      # Unwraps every value object (`{ "value" => x }`) to `x`, at any depth, so a record reads as
+      # `status: "concluded"` and not `status: { value: "concluded" }`. A hash with any other key
+      # is kept as it is, with its own values unwrapped.
+      #
+      # @param node [Object] a hash, an array or a scalar from a stores document
+      # @return [Object] the same shape with each single-`value` hash replaced by its value
+      def flatten(node)
+        case node
+        when Hash then node.keys == ["value"] ? flatten(node["value"]) : node.transform_values { |inner| flatten(inner) }
+        when Array then node.map { |inner| flatten(inner) }
+        else node
+        end
+      end
+
+      # Narrows the whole document to what was asked for: all of it, one aggregate's dump, or
+      # one record of an aggregate as its plain fields.
+      #
+      # @param document [Hash{String => Hash}] `stores_of`'s answer
+      # @param aggregate [String, nil] a storage name from the document; nil keeps everything
+      # @param record [String, nil] a record id within `aggregate`; nil keeps its whole dump
+      # @param names [Array<String>] the storage names to list when `aggregate` is not stored
+      # @return [Hash] the whole document, `{ aggregate => dump }`, or the one record's fields
+      # @raise [Runtime::NotFound] when the aggregate is not stored, the record is not in it, or a
+      #   record is named without an aggregate
+      def narrow(document, aggregate, record, names: document.keys)
+        raise Runtime::NotFound, "name the aggregate the record is in" if record && !aggregate
+        return document unless aggregate
+
+        dump = document.fetch(aggregate) do
+          raise Runtime::NotFound, "no aggregate stored as #{aggregate.inspect}; stored: #{names.join(", ")}"
+        end
+        record ? one_record(dump, aggregate, record) : { aggregate => dump }
+      end
+
+      # The storage names a booted domain keeps records under, read without reading any record.
+      #
+      # @param registry [Runtime::Registry] a booted domain's registry
+      # @return [Array<String>] one storage name per aggregate
+      def stored_names(registry)
+        registry.bluebooks.values.flat_map { |bluebook| bluebook.aggregates.map(&:storage_name) }
+      end
+
+      # @api private
+      def one_record(dump, aggregate, record)
+        dump.fetch("authoritative").find { |row| row["id"] == record } or
+          raise Runtime::NotFound, "no #{aggregate} record with id #{record.inspect}"
+      end
+
       # Reads one aggregate's current records as plain JSON-ready hashes, ordered by id.
       #
       # @param repository [Ports::Persistence::AppendOnly] the aggregate's repository

data/lib/hecks/cli/stress_concurrency_specs/reporting.rb

@@ -6,6 +6,9 @@ module Hecks
       # The verdict of a stress run: the clean line, or each failing run's saved log and how to
       # reproduce it. `StressConcurrencySpecs` extends it.
       module Reporting
+        # A parenthesis, which a saved log's file name leaves out.
+        PARENTHESIS = /[()]/
+
         # @param root [String] the checkout; failing runs' output is saved under its `tmp/`
         # @param results [Array<Hash>] every run's result
         # @param out [IO] where the verdict goes
@@ -33,7 +36,7 @@ module Hecks
         def save_failure(root, failure, out)
           dir = File.join(root, "tmp/stress-failures")
           FileUtils.mkdir_p(dir)
-          path = File.join(dir, "#{failure[:label].tr(" ", "_").gsub(/[()]/, "")}-seed#{failure[:seed]}.log")
+          path = File.join(dir, "#{failure[:label].tr(" ", "_").gsub(PARENTHESIS, "")}-seed#{failure[:seed]}.log")
           File.write(path, failure[:output])
           out.puts "  [#{failure[:label]}] seed #{failure[:seed]} — output saved to #{path.sub("#{root}/", "")}"
           out.puts "    reproduce: #{failure[:reproduce]}"

data/lib/hecks/codemod.rb

@@ -16,7 +16,7 @@ module Hecks
                       Dir.glob(File.join(ROOT, "lib/hecks/framework/bluebook/*.bluebook")) +
                       Dir.glob(File.join(ROOT, "lib/hecks/language/bluebook/**/*.bluebook"))).sort
 
-    # Boots the lightweight, in-memory path — a codemod only reads a chapter's
+    # Boots the lightweight, in-memory path — a codemod only reads a bluebook's
     # own declared IR, never a stored record, so it has no reason to need Postgres.
     PERSISTENCE_PORT = File.join(ROOT, "lib/hecks/ports/persistence.port")
     EXTRACTION_PORT  = File.join(ROOT, "lib/hecks/ports/extraction.port")
@@ -135,8 +135,8 @@ module Hecks
 
     # Walks nested entities recursively too, not just each aggregate's own commands.
     def self.each_command(registry)
-      registry.bluebooks.each_value do |chapter|
-        chapter.aggregates.each do |aggregate|
+      registry.bluebooks.each_value do |declaration|
+        declaration.aggregates.each do |aggregate|
           walk = lambda do |construct|
             construct.commands.each { |command| yield construct, command }
             construct.entities.each(&walk) if construct.respond_to?(:entities)

data/lib/hecks/composer/adapters/claude_composer.rb

@@ -2,6 +2,7 @@ require "json"
 require "open3"
 require "timeout"
 
+require_relative "../../text"
 require_relative "../agent"
 require_relative "jev"
 
@@ -22,7 +23,7 @@ module Hecks
               "for, write the bluebook first, then any hecksagon wiring it needs. Reply with one line " \
               "saying what you changed.".freeze
 
-      WIRE = "Change how the chapter in %<dir>s is wired, as the request below says: edit only its " \
+      WIRE = "Change how the bluebook in %<dir>s is wired, as the request below says: edit only its " \
              ".hecksagon and .world files, and bind adapters that already exist. Reply with one line " \
              "saying what you changed.".freeze
 
@@ -53,7 +54,7 @@ module Hecks
         stdout, status = run(root, message)
         raise Composer::Agent::Unavailable, "claude exited #{status.exitstatus}: #{stdout}" unless status.success?
 
-        { "note" => JSON.parse(stdout).fetch("result").to_s.lines.first.to_s.strip }
+        { "note" => Text.first_line(JSON.parse(stdout).fetch("result")) }
       rescue JSON::ParserError, KeyError => e
         raise Composer::Agent::ValidationError, "claude's reply was not the expected envelope: #{e.message}"
       end

data/lib/hecks/composer/agent.rb

@@ -40,7 +40,7 @@ module Hecks
         note(adapter(registry).draft(prompt: prompt, dir: dir))
       end
 
-      # Asks the agent to change how a workspace's chapter is wired, never what it declares.
+      # Asks the agent to change how a workspace's bluebook is wired, never what it declares.
       #
       # @param registry [Runtime::Registry] a registry holding the port and one adapter for it
       # @param prompt [String] what the author asked for

data/lib/hecks/composer/assistant.rb

@@ -45,8 +45,8 @@ module Hecks
       private
 
       def open_draft(slug, files)
-        chapter = Parse.bluebooks(@workspace).keys.first || "Workspace"
-        @session.open(slug: slug, chapter_name: chapter, text: files.values.first.to_s)
+        declaration = Parse.bluebooks(@workspace).keys.first || "Workspace"
+        @session.open(slug: slug, bluebook_name: declaration, text: files.values.first.to_s)
       end
 
       # The prompt's intent; a classifier that cannot answer leaves it an edit.

data/lib/hecks/composer/behavior_run.rb

@@ -26,12 +26,18 @@ module Hecks
       # @api private
       def report(stage, file)
         {
-          path:        file.path.to_s.delete_prefix("#{File.realpath(stage)}/").delete_prefix("#{stage}/"),
+          path:        relative_path(stage, file.path),
           parse_error: file.parse_error,
           runs:        file.runs.map { |run| run_hash(run) }
         }
       end
 
+      # The file's path inside the staged directory, whether given real or as staged.
+      # @api private
+      def relative_path(stage, path)
+        path.to_s.delete_prefix("#{File.realpath(stage)}/").delete_prefix("#{stage}/")
+      end
+
       # @api private
       def run_hash(run)
         { status: run.status.to_s, description: run.description, message: run.message }

data/lib/hecks/composer/bluebook/composer.bluebook

@@ -1,6 +1,6 @@
-# The Composer chapter: a bluebook being written in an editor, by hand or by asking an agent.
+# The Composer bluebook: a bluebook being written in an editor, by hand or by asking an agent.
 #
-# A Draft is the editor's working copy of one chapter: the text on screen, the conversation that
+# A Draft is the editor's working copy of one bluebook: the text on screen, the conversation that
 # shaped it, and whether the last check of it passed. The files on disk stay the truth; a Draft
 # only holds what is being changed and what was said about it. The check itself (parse, load,
 # project, model-check) and the agent that rewrites the text are the outside, reached through the
@@ -9,10 +9,10 @@ Hecks.bluebook "Composer" do
   vision "Write a bluebook in an editor and watch the domain draw itself, with an agent that can change the draft when asked."
 
   aggregate "Draft" do
-    description "One chapter being edited: its text, the conversation about it, and whether its last check passed."
+    description "One bluebook being edited: its text, the conversation about it, and whether its last check passed."
 
     attribute :slug,         DraftSlug
-    attribute :chapter_name, ChapterName
+    attribute :bluebook_name, BluebookName
     attribute :text,         SourceText
     attribute :note,         Note, optional: true
     attribute :turns,        list_of(Turn)
@@ -20,17 +20,17 @@ Hecks.bluebook "Composer" do
     identified_by :slug
 
     value_object "DraftSlug" do
-      attribute :value, String, pattern: '[^ \t\n\r]'
+      attribute :value, String, matches: :present
 
       invariant("a draft is named") { !value.to_s.empty? }
     end
 
-    # The name a chapter's `Hecks.bluebook "Name"` header declares, which is also the name the
+    # The name a bluebook's `Hecks.bluebook "Name"` header declares, which is also the name the
     # check loads it under.
-    value_object "ChapterName" do
-      attribute :value, String, pattern: '[A-Z][A-Za-z0-9]*'
+    value_object "BluebookName" do
+      attribute :value, String, matches: :capitalized
 
-      invariant("a chapter is named") { !value.to_s.empty? }
+      invariant("a bluebook is named") { !value.to_s.empty? }
     end
 
     # What is on screen. A draft may be empty or half-written; the check judges it, not this.
@@ -60,7 +60,7 @@ Hecks.bluebook "Composer" do
     end
 
     # The sequence is supplied by the caller, who already knows how many turns are on screen, so
-    # the order of a conversation is not a fact this chapter invents on write.
+    # the order of a conversation is not a fact this bluebook invents on write.
     entity "Turn" do
       description "One thing said in the conversation about the draft, by the author or by the agent."
 
@@ -80,15 +80,12 @@ Hecks.bluebook "Composer" do
 
     command "Begin" do
       role "Author"
-      goal "Open a chapter for editing, with the text it starts from"
+      goal "Open a bluebook for editing, with the text it starts from"
 
-      attribute :slug,         DraftSlug
-      attribute :chapter_name, ChapterName
-      attribute :text,         SourceText
+      attribute :slug,         DraftSlug, sets: true
+      attribute :bluebook_name, BluebookName, sets: true
+      attribute :text,         SourceText, sets: true
 
-      sets :slug
-      sets :chapter_name
-      sets :text
 
       emits "DraftBegun"
     end
@@ -98,9 +95,8 @@ Hecks.bluebook "Composer" do
       goal "Replace the draft's text with what is now on screen"
 
       reference_to Draft
-      attribute :text, SourceText
+      attribute :text, SourceText, sets: true
 
-      sets :text
 
       emits "DraftRevised"
     end
@@ -110,9 +106,8 @@ Hecks.bluebook "Composer" do
       goal "Record that the draft's text passed its check"
 
       reference_to Draft
-      attribute :note, Note
+      attribute :note, Note, sets: true
 
-      sets :note
 
       emits "DraftAccepted"
     end
@@ -122,9 +117,8 @@ Hecks.bluebook "Composer" do
       goal "Record that the draft's text failed its check, and why"
 
       reference_to Draft
-      attribute :note, Note
+      attribute :note, Note, sets: true
 
-      sets :note
 
       emits "DraftRejected"
     end
@@ -149,9 +143,8 @@ Hecks.bluebook "Composer" do
       reference_to Draft
       attribute :sequence, TurnSequence
       attribute :said,     Utterance
-      attribute :text,     SourceText
+      attribute :text,     SourceText, sets: true
 
-      sets :text
       sets :turns, append: { sequence: :sequence, speaker: { value: "agent" }, said: :said }
 
       emits "TurnAnswered"

data/lib/hecks/composer/bluebook/composer.hecksagon

@@ -10,7 +10,7 @@ Hecks.hecksagon "Composer" do
   driven_by "Ruby"
 end
 
-# The anti-corruption layer for Governance, which the chapter's roles are checked against.
+# The anti-corruption layer for Governance, which the bluebook's roles are checked against.
 Hecks.hecksagon "Governance" do
   persisted_by "Memory"
 end