hecks 5.0.0 → 6.0.0

data/lib/hecks/rust_build.rb

@@ -43,11 +43,36 @@ module Hecks
     LOCK = Hecks::Adapters::ConsoleCapture::LOCK
     private_constant :LOCK
 
+    # The fiber-local key holding the workspace `in_workspace` chose.
+    WORKSPACE_KEY = :hecks_rust_build_workspace
+    private_constant :WORKSPACE_KEY
+
     class << self
-      # The workspace tools build in: `HECKS_RUST_DIR`, or the gem's own `rust/`.
+      # The workspace tools build in: the one `in_workspace` names, else `HECKS_RUST_DIR`, else the
+      # gem's own `rust/`.
       #
       # @return [String] the directory
-      def rust_dir = ENV.fetch("HECKS_RUST_DIR", File.join(ROOT, "rust"))
+      def rust_dir = workspace || ENV.fetch("HECKS_RUST_DIR", File.join(ROOT, "rust"))
+
+      # Whether a caller chose the workspace, by `in_workspace` or by `HECKS_RUST_DIR`, rather than
+      # the gem's own `rust/` being the default.
+      #
+      # @return [Boolean]
+      def explicit_workspace? = !workspace.nil? || ENV.key?("HECKS_RUST_DIR")
+
+      # Builds in `dir` for the block. A tool run in this process, or in a process forked from
+      # it, reads the workspace from here, so no environment variable carries it.
+      #
+      # @param dir [String] the workspace
+      # @yield the work to do in it
+      # @return [Object] the block's value
+      def in_workspace(dir)
+        saved = workspace
+        Thread.current[WORKSPACE_KEY] = dir
+        yield
+      ensure
+        Thread.current[WORKSPACE_KEY] = saved
+      end
 
       # Runs a tool with the given environment, writing to the given streams.
       #
@@ -129,6 +154,8 @@ module Hecks
 
       private
 
+      def workspace = Thread.current[WORKSPACE_KEY]
+
       def with_streams(out, err)
         saved = [$stdout, $stderr]
         $stdout = out

data/lib/hecks/sentence_form.rb

@@ -0,0 +1,212 @@
+require "digest"
+require "fileutils"
+require "open3"
+require_relative "cache_dir"
+
+module Hecks
+  # A `.bluebook` written as plain sentences (its first line is `Domain: <name>`) rather than in
+  # the Ruby form. The Rust parser is the one reader of the sentences: it renders them as the
+  # Ruby-shaped text that declares the same bluebook, and Ruby evaluates that text under the
+  # sentence file's own path, so the registry records the file the author wrote.
+  module SentenceForm
+    # The repository root, where the parser's build lands under `rust/parser/target/`.
+    ROOT = File.expand_path("../..", __dir__).freeze
+
+    # The line a sentence-form file opens with, after any blank or comment lines.
+    DOMAIN_LINE = /\A\s*Domain:/
+
+    # The first line of a tool's output, without its newline.
+    FIRST_LINE = /\A[^\n]*/
+
+    # A `Hecks.bluebook "Name"` header line, or a `Domain: name` line, capturing the bluebook's
+    # name.
+    BLUEBOOK_HEADER = /\A\s*(?:Hecks\.bluebook\s+"([^"]+)"|Domain:\s*(\S.*?)\s*\z)/
+
+    # Raised when no `hecks-parse` binary can be found.
+    class ParserMissing < StandardError; end
+
+    # Raised when the parser refuses a sentence file; the message is its diagnostic.
+    class Refused < StandardError; end
+
+    module_function
+
+    # @param path [String] a `.bluebook` file
+    # @return [Boolean] whether the file is written as sentences
+    def sentences?(path)
+      first = File.foreach(path).find { |line| !line.strip.empty? && !line.lstrip.start_with?("#") }
+      !first.nil? && first.match?(DOMAIN_LINE)
+    end
+
+    # @param path [String] a bluebook file, in either form
+    # @return [String, nil] the bluebook name its header declares; a `Domain:` line is read as
+    #   the words capitalised and joined, as the parser reads it
+    def declaration_name(path)
+      File.foreach(path) do |line|
+        next unless line =~ BLUEBOOK_HEADER
+
+        return Regexp.last_match(1) || capitalised(Regexp.last_match(2))
+      end
+      nil
+    end
+
+    # @param words [String] the words of a `Domain:` line
+    # @return [String] each word capitalised and the words joined, as the parser reads them
+    def capitalised(words) = words.split.map { |word| word[0].upcase + word[1..] }.join
+
+    # @param text [String] a tool's error output
+    # @return [String] its first line, without the newline
+    def first_line(text) = text.to_s[FIRST_LINE]
+
+    # The Ruby-shaped text of a sentence-form file.
+    #
+    # @param path [String] a sentence-form `.bluebook`
+    # @return [String] Ruby source declaring the same bluebook
+    # @raise [ParserMissing] if `hecks-parse` is not built
+    # @raise [Refused] if the sentences are not ones the parser knows
+    def ruby_text(path)
+      declaration = declaration_name(path) or raise Refused, "#{path}: no `Domain:` line to name the bluebook"
+      out, err, status = Open3.capture3(binary, "render", "--bluebook", declaration, path)
+      raise Refused, first_line(err) unless status.success?
+
+      out
+    end
+
+    # The extension of an examples file: sentences saying who does what to the domain and what
+    # follows, which the behaviors runner runs.
+    EXAMPLES_EXTENSION = ".examples".freeze
+
+    # The first line of an examples file, naming the bluebook the examples are about.
+    EXAMPLES_LINE = /\A\s*Examples for:\s*(\S.*?)\s*\z/
+
+    # @param path [String] a file the behaviors runner was asked to run
+    # @return [Boolean] whether it is an examples file, not a `.behaviors` file
+    def examples?(path) = path.to_s.end_with?(EXAMPLES_EXTENSION)
+
+    # The `.behaviors` text that runs an examples file against its bluebook.
+    #
+    # The bluebook's files are the `.bluebook` beside the examples file with the same stem or, when
+    # there is none, every `.bluebook` there (or in a `bluebook/` folder there) that declares the
+    # bluebook the examples are about.
+    #
+    # @param path [String] an examples file
+    # @return [String] `.behaviors` source
+    # @raise [ParserMissing] if `hecks-parse` is not built
+    # @raise [Refused] if no bluebook file is found or the examples are not ones the parser accepts
+    def behaviors_text(path)
+      declaration = examples_bluebook(path)
+      files = bluebook_files(path, declaration)
+      raise Refused, "#{path}: no .bluebook beside it declares #{declaration}" if files.empty?
+
+      wiring = behaviors_hecksagon(path)
+      also = wiring ? ["--also", wiring] : []
+      out, err, status = Open3.capture3(binary, "examples", "--bluebook", declaration, "--examples", path, *also, *files)
+      raise Refused, first_line(err) unless status.success?
+
+      out
+    end
+
+    # Writes the `.behaviors` text of an examples file where the runner can load it.
+    #
+    # @param path [String] an examples file
+    # @return [String] the generated `.behaviors` file's path
+    def write_behaviors(path)
+      text = behaviors_text(path)
+      dir = CacheDir.path("sentence_form")
+      FileUtils.mkdir_p(dir)
+      generated = File.join(dir, "#{File.basename(path, EXAMPLES_EXTENSION)}-#{Digest::SHA256.hexdigest(text)[0, 16]}.behaviors")
+      File.write(generated, text) unless File.exist?(generated)
+      generated
+    end
+
+    # The Memory-bound hecksagon that answers a bluebook's asks while its examples run: the
+    # `<name>_behaviors.hecksagon` beside the examples file, as Pizzas keeps one beside its own.
+    #
+    # @param path [String] an examples file
+    # @return [String, nil] its absolute path, or nil when there is none
+    def behaviors_hecksagon(path)
+      wiring = File.join(File.dirname(File.expand_path(path)), "#{File.basename(path, EXAMPLES_EXTENSION)}_behaviors.hecksagon")
+      wiring if File.file?(wiring)
+    end
+
+    # @return [String] the bluebook an examples file's first line names, capitalised and joined
+    def examples_bluebook(path)
+      line = File.foreach(path).find { |text| text.match?(EXAMPLES_LINE) }
+      raise Refused, "#{path}: no `Examples for: <bluebook>` line" unless line
+
+      line.match(EXAMPLES_LINE)[1].split.map { |word| word[0].upcase + word[1..] }.join
+    end
+
+    # @return [Array<String>] absolute paths of the `.bluebook` files the examples are about
+    def bluebook_files(path, declaration)
+      dir = File.dirname(File.expand_path(path))
+      same_stem = File.join(dir, "#{File.basename(path, EXAMPLES_EXTENSION)}.bluebook")
+      return [same_stem] if File.file?(same_stem)
+
+      Dir.glob([File.join(dir, "*.bluebook"), File.join(dir, "bluebook", "*.bluebook")])
+         .select { |file| declaration_name(file) == declaration }
+    end
+
+    # Loads a bluebook file in whichever form it is written: sentences through the parser, anything
+    # else as Ruby. Every place that reads a `.bluebook` goes through here, so no boot path accepts
+    # one form and refuses the other.
+    #
+    # @param path [String] a bluebook file, or any other Ruby file
+    # @return [void]
+    def load_file(path)
+      sentences = path.end_with?(".bluebook") && File.file?(path) && sentences?(path)
+      sentences ? load(path) : Kernel.load(path)
+    end
+
+    # Declares the bluebook a sentence-form file holds, in the registry now current.
+    #
+    # The Ruby text is loaded from a file of its own, because a predicate's source is recovered
+    # from the file it was written in; the registry then records the sentence file as the
+    # bluebook's source, not the generated one.
+    #
+    # @param path [String] a sentence-form `.bluebook`
+    # @return [void]
+    def load(path)
+      generated = write_generated(path, ruby_text(path))
+      Kernel.load(generated)
+      point_sources_at(generated, path)
+    end
+
+    # Makes the registry record the sentence file `path` as the source of what `generated` declared.
+    #
+    # @param generated [String] the rendered file that was loaded
+    # @param path [String] the sentence file it came from
+    # @return [void]
+    def point_sources_at(generated, path)
+      registry = Hecks.current_registry
+      registry.bluebook_sources.each_value do |paths|
+        paths.map! { |source| source == generated ? path : source }
+      end
+    end
+
+    # Writes rendered text where Ruby can load it, named by what the text holds so an unchanged
+    # file is written once.
+    #
+    # @param path [String] the sentence file the text was rendered from
+    # @param text [String] the rendered Ruby text
+    # @return [String] the generated file's path
+    def write_generated(path, text)
+      dir = CacheDir.path("sentence_form")
+      FileUtils.mkdir_p(dir)
+      generated = File.join(dir, "#{File.basename(path, ".bluebook")}-#{Digest::SHA256.hexdigest(text)[0, 16]}.bluebook")
+      File.write(generated, text) unless File.exist?(generated)
+      generated
+    end
+
+    # @return [String] the path to `hecks-parse`: `HECKS_PARSE_BIN`, then the release or debug
+    #   build under `rust/parser/target/`, then one on the `PATH`
+    # @raise [ParserMissing] if none exists
+    def binary
+      candidates = [ENV.fetch("HECKS_PARSE_BIN", nil)] +
+                   %w[release debug].map { |profile| File.join(ROOT, "rust/parser/target/#{profile}/hecks-parse") } +
+                   ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).map { |dir| File.join(dir, "hecks-parse") }
+      candidates.compact.find { |path| File.executable?(path) && !File.directory?(path) } or
+        raise ParserMissing, "hecks-parse is not built — run `cargo build --release " \
+                             "--manifest-path rust/parser/Cargo.toml`, or set HECKS_PARSE_BIN"
+    end
+  end
+end

data/lib/hecks/served_options.rb

@@ -1,4 +1,5 @@
 require "rack"
+require_relative "naming"
 
 module Hecks
   # What a domain's world file says it is served by: each `served_by("Adapter") { ... }` line
@@ -48,6 +49,6 @@ module Hecks
       env.fetch(name) { raise ArgumentError, "#{entry[:adapter]}: environment variable #{name} is not set" }
     end
 
-    def snake(name) = name.to_s.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+    def snake(name) = name.to_s.gsub(Naming::CAMEL_BOUNDARY, '\1_\2').downcase
   end
 end

data/lib/hecks/shape_ledger.rb

@@ -0,0 +1,149 @@
+require "fileutils"
+require "json"
+require "hecks"
+
+module Hecks
+  # The committed record of each bluebook's storage shape, held against the shapes the bluebooks
+  # have now, so a shape cannot change without the translation edge that carries a database across.
+  #
+  # A database that holds an era refuses a newer shape no edge leads to. The check that catches
+  # that at a boot only runs against a real database, which specs and gates do not use, so this one
+  # reads nothing but the loaded bluebooks and the committed edges: it needs no database.
+  #
+  # @example
+  #   ShapeLedger.check("lib/hecks/hecks")  # => "15 bluebook shapes, each the one the ledger holds"
+  module ShapeLedger
+    # The ledger file, beside the bluebooks it records.
+    FILE = "shapes.json".freeze
+
+    # The length of the label a translation edge names a shape by.
+    LABEL = 6
+
+    # What a problem line tells the reader to do.
+    REWRITE = "rewrite the ledger with `hecks conformance_run.check_shape_ledger --confirm --wait`".freeze
+
+    # Raised with every problem found, or when the ledger cannot be rewritten.
+    class Failure < StandardError; end
+
+    module_function
+
+    # Compares the ledger with the shapes of the bluebooks under a directory.
+    #
+    # @param directory [String] the domain directory whose bluebooks the ledger records
+    # @param confirm [Boolean] rewrite the ledger when every moved shape has an edge
+    # @param additive [Boolean] with `confirm`, write the empty edge for each shape that moved with
+    #   none, on the operator's word that the change only adds; the mint audits every edge against
+    #   the records it migrates and refuses one that would lose data
+    # @return [String] the clean verdict, or what was written
+    # @raise [Failure] with each problem
+    def check(directory, confirm: false, additive: false)
+      registry = Hecks.describe(directory).registry
+      shapes = shapes_of(registry)
+      edges = edges_of(registry)
+      path = File.join(directory, FILE)
+      confirm ? rewrite(path, shapes, edges, directory, additive) : verdict(path, shapes, edges)
+    end
+
+    # @param registry [Runtime::Registry] the loaded bluebooks
+    # @return [Hash{String => String}] each bluebook's storage-shape hash, by name
+    def shapes_of(registry)
+      registry.bluebooks.to_h { |name, bluebook| [name, Runtime::StorageShape.mint_hash(bluebook)] }
+    end
+
+    # @param registry [Runtime::Registry] the loaded bluebooks
+    # @return [Hash{String => Array<Array(String, String)>}] each bluebook's edges as `[from, to]`
+    def edges_of(registry)
+      registry.translations.group_by(&:domain).transform_values { |edges| pairs(edges) }
+    end
+
+    def pairs(edges) = edges.map { |edge| [edge.from, edge.to] }
+
+    def label(hash) = hash.to_s[0, LABEL]
+
+    # @return [Boolean] whether a chain of edges leads from one label to another
+    def reachable?(from, to, edges)
+      seen = [from]
+      queue = [from]
+      queue.concat(next_labels(queue.shift, edges, seen)) until queue.empty? || seen.include?(to)
+      seen.include?(to)
+    end
+
+    def next_labels(at, edges, seen)
+      fresh = edges.filter_map { |from, to| to if from == at && !seen.include?(to) }
+      seen.concat(fresh)
+      fresh
+    end
+
+    def verdict(path, shapes, edges)
+      problems = problems(read(path), shapes, edges)
+      raise Failure, problems.join("\n") unless problems.empty?
+
+      "#{shapes.size} bluebook shapes, each the one the ledger holds"
+    end
+
+    # @return [Array<String>] one line per bluebook whose shape disagrees with the ledger
+    def problems(ledger, shapes, edges)
+      moved = shapes.filter_map { |name, now| problem(name, ledger[name], now, edges.fetch(name, [])) }
+      moved + (ledger.keys - shapes.keys).map { |name| "#{name}: in the ledger but no longer loaded; #{REWRITE}" }
+    end
+
+    def problem(name, held, now, edges)
+      return "#{name}: not in the ledger (shape #{label(now)}); #{REWRITE}" unless held
+      return nil if label(held) == label(now)
+
+      change = "#{name}: the shape moved #{label(held)} -> #{label(now)}"
+      return "#{change}, and an edge covers it; #{REWRITE}" if reachable?(label(held), label(now), edges)
+
+      "#{change} with no translation edge from #{label(held)}; #{edge_advice(name, label(held), label(now))}"
+    end
+
+    # What to commit: the empty edge covers a change that only adds, and a change that renames or
+    # reshapes data needs the rules the scaffold writes from the database that holds the eras.
+    def edge_advice(name, from, now)
+      edge = %(Hecks.data_translation "#{name}", from: "#{from}", to: "#{now}" do end)
+      "for a change that only adds, commit this edge under translations/ (as 2-#{now}.bluebook): #{edge}. " \
+        "Data that is renamed or reshaped needs rules: `hecks query era.scaffold_translation " \
+        "domain.value=<directory>` writes them, reading the eras from the database the domain's " \
+        "own world names. A change that only adds is settled in one step " \
+        "by `hecks conformance_run.check_shape_ledger --confirm --additive --wait`"
+    end
+
+    def rewrite(path, shapes, edges, directory, additive)
+      ledger = read(path)
+      written = additive ? write_edges(directory, uncovered_moves(ledger, shapes, edges)) : []
+      uncovered = additive ? [] : problems(ledger, shapes, edges).reject { |line| line.include?(REWRITE) }
+      raise Failure, uncovered.join("\n") unless uncovered.empty?
+
+      File.write(path, "#{JSON.pretty_generate(shapes.sort.to_h)}\n")
+      "wrote #{shapes.size} bluebook shapes to #{path}#{edges_note(written)}"
+    end
+
+    def edges_note(written) = written.empty? ? "" : " and #{written.size} empty edge(s): #{written.join(", ")}"
+
+    # @return [Array<Array(String, String, String)>] `[bluebook, from, to]` for each shape that
+    #   moved
+    #   with no chain of edges leading to it
+    def uncovered_moves(ledger, shapes, edges)
+      shapes.filter_map do |name, now|
+        held = ledger[name]
+        next unless held && label(held) != label(now)
+        next if reachable?(label(held), label(now), edges.fetch(name, []))
+
+        [name, label(held), label(now)]
+      end
+    end
+
+    # @return [Array<String>] the paths of the empty edges written
+    def write_edges(directory, moves)
+      FileUtils.mkdir_p(File.join(directory, "translations"))
+      moves.map do |name, from, now|
+        path = File.join(directory, "translations", "2-#{now}.bluebook")
+        File.write(path, %(Hecks.data_translation "#{name}", from: "#{from}", to: "#{now}" do\nend\n))
+        path
+      end
+    end
+
+    # @return [Hash{String => String}] the ledger, empty when there is none yet
+    def read(path) = File.exist?(path) ? JSON.parse(File.read(path)) : {}
+  end
+end

data/lib/hecks/site/bluebook/site.bluebook

@@ -1,23 +1,23 @@
-# The Site chapter: the route table a client declares for its website, and the command that
+# The Site bluebook: the route table a client declares for its website, and the command that
 # projects it into the TypeScript the site reads.
 #
-# A client declares its routes as `member` rows of a `value_object "Route"` in its own chapter (the
+# A client declares its routes as `member` rows of a `value_object "Route"` in its own bluebook (the
 # Route aggregate below names every field a row may carry and the closed sets its values come from),
-# attaches this chapter, and runs `hecks site site_projection.project_site`. The projection (`:site_routes_ts`)
+# attaches this bluebook, and runs `hecks site site_projection.project_site`. The projection (`:site_routes_ts`)
 # writes one `routes.ts` the site's middleware, navigation, sitemap, robots file and CMS all import,
 # so a route is declared once. The Route aggregate's value objects are the one place the closed
 # vocabularies live: the projector reads them from here, so a row naming a cache class that is
 # not a member is refused with the members listed.
 #
 # The same command projects the CDN: a project that adds Edge, EdgePolicy, EdgeOrigin and EdgeRule rows
-# to its chapter has the CloudFront behaviours and the listener rules written into the marked regions
+# to its bluebook has the CloudFront behaviours and the listener rules written into the marked regions
 # of the template it owns (the `:site_cdn` projection). Those rows are the template's facts, so only the
 # closed sets they draw on, cache class, origin and the kind of an EdgeFunction row, are named here. A
 # route's `edge:` names an EdgeFunction row, a viewer-request function the projection writes into the
 # template's `edge_functions` region and attaches to that route's behaviour.
 #
 # Each run records that it was requested before the SiteToolchain port is asked, and what came of
-# it after. No command declares a role: the chapter boots standing alone.
+# it after. No command declares a role: the bluebook boots standing alone.
 Hecks.bluebook "Site" do
   vision "Declare a site's routes once and project them into the TypeScript its pages, navigation and CMS read."
 
@@ -39,7 +39,7 @@ Hecks.bluebook "Site" do
 
     # `/blog/:slug.html` names a parameter; a trailing `/*` matches everything beneath a prefix. A
     # row with a `command:` or `query:` source may leave its path out, and the projection derives it
-    # from the forms scheme (`/Chapter/Aggregate/Verb`).
+    # from the forms scheme (`/Bluebook/Aggregate/Verb`).
     value_object "Path" do
       attribute :value, String, pattern: '\A(/[^ \t\n\r]*)?\z'
     end
@@ -100,8 +100,8 @@ Hecks.bluebook "Site" do
 
     # Where a page's content comes from, one of `none`, `global:<slug>` (a CMS global),
     # `collection:<name>` (a CMS collection, whose rows fill the path's parameter),
-    # `command:<Chapter>.<Aggregate>.<Command>` or `query:<Chapter>.<Aggregate>.<Query>`. The last
-    # two are checked against the chapters the project attaches.
+    # `command:<Bluebook>.<Aggregate>.<Command>` or `query:<Bluebook>.<Aggregate>.<Query>`. The last
+    # two are checked against the bluebooks the project attaches.
     value_object "Source" do
       attribute :value, String, pattern: '\A(none|(global|collection):[a-z0-9_-]+|(command|query):[A-Za-z0-9_]+\.[A-Za-z0-9_]+\.[A-Za-z0-9_]+)\z'
     end
@@ -134,7 +134,7 @@ Hecks.bluebook "Site" do
       invariant("a run is named") { !value.to_s.empty? }
     end
 
-    # A project directory, whose `bluebook/` holds the chapter that declares the route table.
+    # A project directory, whose `bluebook/` holds the bluebook that declares the route table.
     value_object "DomainPath" do
       attribute :value, String, matches: :not_empty
 
@@ -185,6 +185,7 @@ Hecks.bluebook "Site" do
       mark :failure, "faulted"
       transition "Complete" => "projected", from: "requested"
       transition "Fault"    => "faulted",   from: "requested"
+      mark :terminal, "faulted", "projected"
     end
 
     # `hecks site site_projection.project_site <project> [out=<dir>] [template=<file>] [cms=<dir>] [root=<dir>] [editor=<dir>] [extension=ts|mts] [--check]`.
@@ -193,25 +194,16 @@ Hecks.bluebook "Site" do
     command "ProjectSite" do
       goal "Project a site's route table into routes.ts, or with check only compare it with the file on disk"
 
-      attribute :domain,    DomainPath
-      attribute :run,       RunKey
-      attribute :out,       Location,  optional: true
-      attribute :template,  Location,  optional: true
-      attribute :cms,       Location,  optional: true
-      attribute :root,      Location,  optional: true
-      attribute :editor,    Location,  optional: true
-      attribute :extension, Extension, optional: true
-      attribute :check,     Switch,    optional: true
-
-      sets :domain
-      sets :run
-      sets :out
-      sets :template
-      sets :cms
-      sets :root
-      sets :editor
-      sets :extension
-      sets :check
+      attribute :domain,    DomainPath, sets: true
+      attribute :run,       RunKey, sets: true
+      attribute :out,       Location,  optional: true, sets: true
+      attribute :template,  Location,  optional: true, sets: true
+      attribute :cms,       Location,  optional: true, sets: true
+      attribute :root,      Location,  optional: true, sets: true
+      attribute :editor,    Location,  optional: true, sets: true
+      attribute :extension, Extension, optional: true, sets: true
+      attribute :check,     Switch,    optional: true, sets: true
+
 
       emits "SiteProjectionRequested"
     end
@@ -226,25 +218,18 @@ Hecks.bluebook "Site" do
     command "CheckLive" do
       goal "Compare a project's generated CloudFront behaviours with a live distribution's"
 
-      attribute :domain,       DomainPath
-      attribute :run,          RunKey
-      attribute :template,     Location,       optional: true
-      attribute :live,         Location,       optional: true
-      attribute :distribution, DistributionId, optional: true
-      attribute :expect_new,   PathList,       optional: true
-      attribute :refs,         PolicyRefs,     optional: true
+      attribute :domain,       DomainPath, sets: true
+      attribute :run,          RunKey, sets: true
+      attribute :template,     Location,       optional: true, sets: true
+      attribute :live,         Location,       optional: true, sets: true
+      attribute :distribution, DistributionId, optional: true, sets: true
+      attribute :expect_new,   PathList,       optional: true, sets: true
+      attribute :refs,         PolicyRefs,     optional: true, sets: true
 
       given("exactly one of a saved configuration and a distribution is named: pass live= or distribution=, not both") do
         (live.set? && distribution.unset?) || (live.unset? && distribution.set?)
       end
 
-      sets :domain
-      sets :run
-      sets :template
-      sets :live
-      sets :distribution
-      sets :expect_new
-      sets :refs
 
       emits "LiveCheckRequested"
     end
@@ -258,13 +243,10 @@ Hecks.bluebook "Site" do
     command "CheckSite" do
       goal "Ask a running site what its route table says it must answer, and judge each answer"
 
-      attribute :domain, DomainPath
-      attribute :run,    RunKey
-      attribute :url,    SiteUrl
+      attribute :domain, DomainPath, sets: true
+      attribute :run,    RunKey, sets: true
+      attribute :url,    SiteUrl, sets: true
 
-      sets :domain
-      sets :run
-      sets :url
 
       emits "SiteProbeRequested"
     end
@@ -277,13 +259,10 @@ Hecks.bluebook "Site" do
     command "CheckRoles" do
       goal "Check a host on this machine refuses every role-declaring command from a caller with no role"
 
-      attribute :domain, DomainPath
-      attribute :run,    RunKey
-      attribute :url,    SiteUrl
+      attribute :domain, DomainPath, sets: true
+      attribute :run,    RunKey, sets: true
+      attribute :url,    SiteUrl, sets: true
 
-      sets :domain
-      sets :run
-      sets :url
 
       emits "RolesCheckRequested"
     end
@@ -292,9 +271,8 @@ Hecks.bluebook "Site" do
       goal "Record that routes.ts was written, or found current, or the live edge matched, and what it said"
 
       reference_to SiteProjection
-      attribute :output, Report
+      attribute :output, Report, sets: true
 
-      sets :output
 
       emits "SiteProjected"
     end
@@ -303,9 +281,8 @@ Hecks.bluebook "Site" do
       goal "Record that routes.ts could not be projected, or was out of date, and why"
 
       reference_to SiteProjection
-      attribute :refusal, Report
+      attribute :refusal, Report, sets: true
 
-      sets :refusal
 
       emits "SiteFaulted"
     end
@@ -326,22 +303,22 @@ Hecks.bluebook "Site" do
 
   policy "ProjectWhenRequested" do
     on      "SiteProjection.SiteProjectionRequested"
-    trigger SiteProjection::SiteToolchain::Project, with: { run: :run }
+    ask     :project, with: { run: :run }
   end
 
   policy "CheckWhenRequested" do
     on      "SiteProjection.LiveCheckRequested"
-    trigger SiteProjection::SiteToolchain::Compare, with: { run: :run }
+    ask     :compare, with: { run: :run }
   end
 
   policy "ProbeWhenRequested" do
     on      "SiteProjection.SiteProbeRequested"
-    trigger SiteProjection::SiteToolchain::Probe, with: { run: :run }
+    ask     :probe, with: { run: :run }
   end
 
   policy "RolesWhenRequested" do
     on      "SiteProjection.RolesCheckRequested"
-    trigger SiteProjection::SiteToolchain::Roles, with: { run: :run }
+    ask     :roles, with: { run: :run }
   end
 
   policy "RecordTheProjection" do

data/lib/hecks/site/bluebook/site.ports.hecksagon

@@ -1,4 +1,4 @@
-# The port Site declares, for every hecksagon that attaches the chapter (`Chapters` loads this file
+# The port Site declares, for every hecksagon that attaches the bluebook (`Bluebooks` loads this file
 # with it). Each projection asks the SiteToolchain port, which the Hecks domain binds
 # (lib/hecks/hecks/adapters/site_toolchain.rb): the outside a projection reaches. The ask is
 # answered with the record's own arguments or refused with a reason. The port has to be declared