hecks 5.0.0 → 7.0.0

data/lib/hecks/hecks/adapters/settings_reading/disposable_ledger.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    class SettingsReading
+      # The `disposable ledger` row of `hecks config`: whether the copy's world declares its
+      # PostgresEra store a disposable tooling ledger, which needs no era for a shape change, and
+      # whether the world or the default says so.
+      module DisposableLedger
+        # @param directory [String] the domain directory
+        # @return [Array(String, String, String)] the row's name, value and source
+        def disposable_ledger(directory)
+          registry = Hecks.describe(directory).registry
+          declared = registry.binding_settings(registry.first_domain_name, Ports::Persistence::VERB, "PostgresEra")
+          ["disposable ledger", disposable_wording(declared), declared.key?(:disposable_ledger) ? "world" : "default"]
+        rescue StandardError => e
+          ["disposable ledger", "could not be read", first_line(e.message)]
+        end
+
+        private
+
+        def disposable_wording(declared)
+          if [true, "true"].include?(declared[:disposable_ledger])
+            "yes: a shape change needs no era, and a breaking one archives its rows"
+          else
+            "no: a shape change needs an era"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/settings_reading/push_nudge.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "../../../quality_control/adapters/push_due_reader"
+
+module Hecks
+  module Adapters
+    class SettingsReading
+      # The `push nudge` row of `hecks config`: how many commits or hours local main may drift ahead
+      # of origin/main before QA files the `push-due` Work row, how many commits make it urgent, and
+      # whether the QualityControl world or the default says so.
+      module PushNudge
+        # @param directory [String] the domain directory
+        # @return [Array(String, String, String)] the row's name, value and source
+        def push_nudge(directory)
+          registry = Hecks.describe(directory).registry
+          declared = registry.world("QualityControl")&.for_verb(PushDueReader::VERB)
+          limits = PushDueReader.thresholds(registry)
+          value = "#{limits[:commits]} commits or #{limits[:hours]} hours, urgent at #{limits[:urgent_commits]} commits"
+          ["push nudge", value, declared ? "world" : "default"]
+        rescue StandardError => e
+          ["push nudge", "could not be read", first_line(e.message)]
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/settings_reading/stores.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    class SettingsReading
+      # The store rows of `hecks config`: each loaded bluebook's store, and the aggregates whose own
+      # bind overrides it. Resolved through the runtime's binding policy, so these rows cannot
+      # disagree with a boot.
+      module Stores
+        # The adapter names the store rows recognise by their storage.
+        SQLITE = /Sqlite/
+        POSTGRES = /Postgres/
+
+        # cannot disagree with a boot.
+        def stores(directory)
+          registry = Hecks.describe(directory).registry
+          registry.bluebooks.each_value.flat_map { |declaration| store_rows(registry, declaration) }
+        rescue StandardError => e
+          [["store", "could not be read", first_line(e.message)]]
+        end
+
+        def store_rows(registry, declaration)
+          name = declaration.name
+          adapter = registry.default_adapter_for(name) || Ports::Persistence::BindingPolicy.inherited_adapter(registry,
+                                                                                                              name) || DEFAULT
+          [["store #{name}", store_of(registry, name, adapter), default_store_source(registry, name)],
+           *aggregate_store_rows(registry, declaration)]
+        end
+
+        def aggregate_store_rows(registry, declaration)
+          declaration.aggregates.filter_map do |aggregate|
+            next unless bound_here?(registry, declaration.name, aggregate)
+
+            bind = Ports::Persistence::BindingPolicy.resolve(registry, declaration.name, aggregate)
+            ["store #{declaration.name}::#{aggregate.name}", store_of(registry, declaration.name, bind.adapter),
+             "aggregate bind in the hecksagon"]
+          end
+        end
+
+        def bound_here?(registry, domain, aggregate)
+          registry.hecksagon(domain)&.binds&.any? { |bind| named?(bind, aggregate) && bind.verb == VERB } || false
+        end
+
+        # A bind names its aggregate bare or qualified by its bluebook (`Tickets::Work`), as the
+        # hecksagon wrote it.
+        def named?(bind, aggregate)
+          bind.aggregate.to_s.split("::").last == aggregate.hecks_name
+        end
+
+        def default_store_source(registry, name)
+          return "hecksagon" if registry.hecksagon(name)&.default_binds(VERB)&.any?
+          return "world default_adapter" if registry.default_adapter_for(name)
+          return "attaching domain's root default" if Ports::Persistence::BindingPolicy.inherited_adapter(registry, name)
+
+          "default"
+        end
+
+        def store_of(registry, domain, adapter)
+          settings = registry.binding_settings(domain, VERB, adapter)
+          case adapter
+          when DEFAULT then DEFAULT
+          when SQLITE then "SqliteAt #{settings[:database]}"
+          when POSTGRES then "Postgres #{database_name(settings[:database])}"
+          else adapter
+          end
+        end
+
+        # The database's name from a URL, with the password hidden and the query string left out.
+        def database_name(url)
+          without_query = hide_password(url).split("?").first.to_s
+          without_query.split("/").last.to_s
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/settings_reading/test_scope.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "../codebase/test_scope"
+
+module Hecks
+  module Adapters
+    class SettingsReading
+      # The `test scope` row of `hecks config`: where the full spec suite runs and how many spec
+      # files one local call may run, and whether the Hecks world or the default says so.
+      module TestScope
+        # @param directory [String] the domain directory
+        # @return [Array(String, String, String)] the row's name, value and source
+        def test_scope(directory)
+          declared = Codebase::TestScope.setting(Hecks.describe(directory).registry)
+          return ["test scope", "no limit", "default"] if declared.empty?
+
+          ["test scope", wording(declared), "world"]
+        rescue StandardError => e
+          ["test scope", "could not be read", first_line(e.message)]
+        end
+
+        def wording(declared)
+          "full suite in #{declared[:suite_runs_in]}; at most #{declared[:spec_files_limit]} spec files per call locally"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/settings_reading.adapter

@@ -0,0 +1,7 @@
+# Required by name, not relative to this file: a fuzz or model check boots a copy of this directory,
+# and the implementation must load once, from `lib/`, not from the copy.
+require "hecks/hecks/adapters/settings_reading"
+
+Hecks.adapter "SettingsReading" do
+  port "Settings"
+end

data/lib/hecks/hecks/adapters/settings_reading.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require "hecks"
+require_relative "console_capture"
+require_relative "../../ports/persistence/binding_policy"
+require_relative "settings_reading/stores"
+require_relative "settings_reading/disposable_ledger"
+require_relative "settings_reading/push_nudge"
+require_relative "settings_reading/test_scope"
+require_relative "work_limits"
+
+module Hecks
+  module Adapters
+    # The `Settings` port's adapter for `Checkout`: what a copy resolves for each setting that can
+    # come from a variable, the copy's own world or a default, and which of the three supplied it.
+    # It reads and never writes, and prints no secret: a database URL's password is hidden.
+    #
+    # The query takes `domain`, a domain directory (the current directory when absent), and
+    # answers `text:`, one `name: value (source)` line each, then any deprecated variable that is
+    # set. A setting the domain cannot resolve is shown as such, not left out.
+    class SettingsReading
+      # The variables no code reads; one that is set is reported as ignored.
+      RETIRED = %w[HECKS_PRE_PUSH_GATE HECKS_EVAL HECKS_FUZZ_SCHEMA].freeze
+
+      # The persistence verb and the store a domain with no bind of its own uses.
+      VERB = Ports::Persistence::VERB
+      DEFAULT = Ports::Persistence::DEFAULT_ADAPTER
+
+      include Stores
+      include DisposableLedger
+      include PushNudge
+      include TestScope
+
+      # The first line of a message.
+      FIRST_LINE = /\A[^\n]*/
+
+      # A URL's password: `user:secret@` becomes `user:***@`.
+      PASSWORD = %r{(://[^:/@\s]+):[^@\s]+@}
+
+      # Accepts the arguments every driven adapter is built with and keeps none of them.
+      #
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] unused
+      def initialize(aggregate: nil, settings: {}, root: nil); end
+
+      # @param held [Hash] `domain`, a domain directory
+      # @return [Hash{Symbol => String}] `text:` the resolved settings
+      # @raise [ConsoleCapture::Failure] when the directory is not there
+      def settings(**held)
+        directory = plain(held[:domain]) || Dir.pwd
+        raise ConsoleCapture::Failure, "#{directory} is not a directory" unless File.directory?(directory)
+
+        { text: (rows(directory).map { |row| line_of(*row) } + deprecated).join("\n") }
+      end
+
+      private
+
+      def rows(directory)
+        [environment, database(directory), mint_eras(directory), disposable_ledger(directory), work_cap(directory),
+         push_nudge(directory), test_scope(directory),
+         schema, project_environment,
+         variable_or_default("cache directory", "HECKS_CACHE_DIR", usage_cache_directory),
+         variable_or_default("rust workspace", "HECKS_RUST_DIR", RustBuild.rust_dir),
+         registry_source(directory), *stores(directory)]
+      end
+
+      def line_of(name, value, source) = "#{name}: #{value} (#{source})"
+
+      def environment
+        named = ENV.fetch("HECKS_ENVIRONMENT", "")
+        named.empty? ? ["environment", "none", "default"] : ["environment", named, "variable HECKS_ENVIRONMENT"]
+      end
+
+      # The world's `default_database`, and which of a local world or the world itself supplied it.
+      def database(directory)
+        value = declared_database(directory) || "none declared"
+        ["database", hide_password(value), database_source(directory)]
+      rescue StandardError => e
+        ["database", "could not be read", first_line(e.message)]
+      end
+
+      def database_source(directory) = local_world(directory) || "world"
+
+      # The copy's own world that can supply the database: `environments/local.world`, else a
+      # `<bluebook>.local.world` beside the domain or in the working directory.
+      def local_world(directory)
+        return "environments/local.world" if File.exist?(File.join(directory, "environments", "local.world"))
+
+        found = [directory, Dir.pwd].uniq.flat_map { |where| Dir[File.join(where, "*.local.world")] }.first
+        found && File.basename(found)
+      end
+
+      def declared_database(directory)
+        registry = Hecks.describe(directory).registry
+        name = registry.first_domain_name
+        name && registry.default_database_for(name)
+      end
+
+      def first_line(text) = text.to_s[FIRST_LINE].strip
+
+      # Whether this copy may migrate its database to a newer storage shape, and whether the world
+      # says so or the default does.
+      def mint_eras(directory)
+        registry = Hecks.describe(directory).registry
+        declared = registry.binding_settings(registry.first_domain_name, Ports::Persistence::VERB, "PostgresEra")
+        ["mint eras", mint_wording(declared), declared.key?(:mint_eras) ? "world" : "default"]
+      rescue StandardError => e
+        ["mint eras", "could not be read", first_line(e.message)]
+      end
+
+      # How many Work rows may be started at once, and whether the world or the default says.
+      def work_cap(directory)
+        registry = Hecks.describe(directory).registry
+        declared = registry.world("Tickets")&.for_verb(WorkLimits::VERB)&.key?(:cap)
+        ["work cap", WorkLimits.cap(registry), declared ? "world" : "default"]
+      rescue StandardError => e
+        ["work cap", "could not be read", first_line(e.message)]
+      end
+
+      def mint_wording(declared)
+        require "hecks/adapters/driven/postgres_era"
+        default = PostgresEra::LineageManager::EraResolver::MINT_BY_DEFAULT
+        [true, "true"].include?(declared.fetch(:mint_eras, default)) ? "allowed" : "refused"
+      end
+
+      def schema
+        return ["schema", ENV.fetch("HECKS_SCHEMA"), "variable HECKS_SCHEMA"] unless ENV.fetch("HECKS_SCHEMA", "").empty?
+
+        ["schema", "the world's, else one derived from the domain's name", "default"]
+      end
+
+      def project_environment
+        named = ENV.fetch("HECKS_PROJECT_ENVIRONMENT", "")
+        return ["project environment", "none", "default"] if named.empty?
+
+        ["project environment", named, "variable HECKS_PROJECT_ENVIRONMENT"]
+      end
+
+      def usage_cache_directory
+        require "hecks/adapters/driving/usage_cache"
+        Hecks::Adapters::Driving::UsageCache.directory
+      end
+
+      def registry_source(directory)
+        require "hecks/embryonaut_bluebook/vendor_cli"
+        found = Hecks::EmbryonautBluebook::VendorCli.default_source(directory)
+        return ["registry source", "none found", "default"] unless found
+
+        named = ENV.fetch("EMBRYONAUT_BLUEBOOKS_SRC", nil)
+        ["registry source", found, named ? "variable EMBRYONAUT_BLUEBOOKS_SRC" : "beside the project"]
+      end
+
+      def variable_or_default(name, variable, value)
+        [name, value, ENV.fetch(variable, nil) ? "variable #{variable}" : "default"]
+      end
+
+      def deprecated
+        set = RETIRED.select { |name| ENV.fetch(name, nil) }
+        set.empty? ? [] : ["retired variables set, and ignored: #{set.join(", ")}"]
+      end
+
+      def hide_password(url) = url.to_s.gsub(PASSWORD, '\1:***@')
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+    end
+  end
+end

data/lib/hecks/hecks/adapters/shell.rb

@@ -21,6 +21,9 @@ module Hecks
       Result = Struct.new(:out, :err, :status) do
         # @return [Boolean] whether the program ended with status 0
         def ok? = status.success?
+
+        # @return [Integer, nil] the status the program ended with, or nil when a signal ended it
+        def exit_code = status.exitstatus
       end
 
       # Accepts the arguments every driven adapter is built with and keeps none of them.

data/lib/hecks/hecks/adapters/site_toolchain.rb

@@ -131,9 +131,9 @@ module Hecks
 
       # The project's checked edge, read the way `project_site` reads it.
       def edge_of(root, template = nil)
-        registry, chapter, table = read_table(root)
+        registry, declaration, table = read_table(root)
         site = Projections::Site
-        site::Edge.read(chapter, table: table, template: template, vocabulary: site::Table.vocabulary(registry)) ||
+        site::Edge.read(declaration, table: table, template: template, vocabulary: site::Table.vocabulary(registry)) ||
           raise(ConsoleCapture::Failure, "#{root} declares no Edge rows")
       end
 
@@ -149,11 +149,11 @@ module Hecks
         registry
       end
 
-      # The registry, chapter and checked table of the project at `root`.
+      # The registry, bluebook and checked table of the project at `root`.
       def read_table(root)
         registry = registry_of(root)
-        chapter = Projections::Site::Table.chapter(registry)
-        [registry, chapter, Projections::Site::Table.read(chapter, registry: registry)]
+        declaration = Projections::Site::Table.declaration(registry)
+        [registry, declaration, Projections::Site::Table.read(declaration, registry: registry)]
       rescue Projections::Site::Table::Invalid => e
         raise ConsoleCapture::Failure, e.message
       end
@@ -164,7 +164,7 @@ module Hecks
         text = file ? read_saved(file) : fetch(id)
         JSON.parse(text)
       rescue JSON::ParserError => e
-        raise ConsoleCapture::Failure, "the live configuration is not JSON: #{e.message.lines.first.strip}"
+        raise ConsoleCapture::Failure, "the live configuration is not JSON: #{Text.first_line(e.message)}"
       end
 
       def read_saved(path)
@@ -181,11 +181,11 @@ module Hecks
         raise ConsoleCapture::Failure, "aws cloudfront get-distribution-config failed: #{message_of(result)}"
       end
 
-      def words(argument) = plain(argument).to_s.split(",").map(&:strip).reject(&:empty?)
+      def words(argument) = Text.comma_list(plain(argument))
 
       def message_of(result)
         text = [result.err, result.out].map(&:strip).reject(&:empty?).join("\n")
-        text.empty? ? "the tool ended with status #{result.status.exitstatus}" : text
+        text.empty? ? "the tool ended with status #{result.exit_code}" : text
       end
 
       # The tool runs from the tool's own root, so a path the caller gave relative to where they

data/lib/hecks/hecks/adapters/started_work.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    # The started `Tickets::Work` rows of a booted registry, with the area each one claims. The
+    # `WorkAreas` and `Landing` adapters both read claims through this.
+    module StartedWork
+      module_function
+
+      # @param registry [Runtime::Registry, nil] the booted registry; nil reads no rows
+      # @return [Array<Hash{Symbol => Object}>] `key:` and `area:` (strings) of each started row
+      def rows(registry)
+        aggregate = work_aggregate(registry)
+        return [] unless aggregate
+
+        registry.repository("Tickets", aggregate).all.filter_map { |record| row(record) }
+      end
+
+      # @return [Object, nil] the Work aggregate, nil when no Tickets bluebook is booted
+      def work_aggregate(registry)
+        bluebook = registry&.bluebook("Tickets")
+        bluebook&.aggregates&.find { |candidate| candidate.hecks_name == "Work" }
+      end
+
+      # @return [Hash, nil] the row's key and area, nil unless the row is started
+      def row(record)
+        return unless value(record, :status) == "started"
+
+        { key: value(record, :work).to_s, area: words(value(record, :area)) }
+      end
+
+      # @return [Array<String>] the areas of a list of Word values
+      def words(list) = Array(list).map { |word| (value(word, :value) || word).to_s }
+
+      # @return [Object] a field of a record or hash, unwrapped from its value object
+      def value(record, name)
+        found = record.respond_to?(name) ? record.public_send(name) : (record[name] if record.respond_to?(:[]))
+        found.respond_to?(:value) ? found.value : found
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/terminal.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "console_capture"
-require "hecks/cli/console"
+require "hecks/tools/console"
 
 module Hecks
   module Adapters
@@ -17,7 +17,7 @@ module Hecks
         attr_accessor :launcher
 
         # @return [#call, nil] serves MCP over stdio, given the arguments after the command;
-        #   `Hecks::CLI::Mcp.call` when nil
+        #   `Hecks::Tools::Mcp.call` when nil
         attr_accessor :server
       end
 
@@ -38,7 +38,7 @@ module Hecks
         subject = held[:subject]
         domain  = subject.is_a?(Hash) ? subject[:value] : subject
         launcher = self.class.launcher
-        launcher ? CLI::Console.call(domain, launcher: launcher) : CLI::Console.call(domain)
+        launcher ? Tools::Console.call(domain, launcher: launcher) : Tools::Console.call(domain)
 
         { output: { value: "console session ended (#{domain || "pizzas"})" } }
       end
@@ -49,13 +49,15 @@ module Hecks
       # only once the client is gone.
       #
       # @param held [Hash] the `Launch` record: `stdio` (whether `--stdio` was given)
-      # @return [Hash{Symbol => Hash}] `output:` a one-line note that the server closed
+      # @return [Hash{Symbol => Hash}] `report:` a one-line note that the server closed, which the
+      #   run records as its outcome; `output:` carries the same note for the launcher's answer
       # @raise [ConsoleCapture::Failure] when the process is not set up for stdio: the server
       #   refused to start, and said why on stderr
       def serve(**held)
         run_server(plain(held[:stdio]) ? ["--stdio"] : [])
 
-        { output: { value: "mcp server closed" } }
+        note = { value: "mcp server closed" }
+        { report: note, output: note }
       rescue SystemExit => e
         raise ConsoleCapture::Failure, "the mcp server refused to start (status #{e.status}); see stderr"
       end
@@ -68,9 +70,9 @@ module Hecks
       # @return [Hash{Symbol => Hash}] `output:` what the interview wrote, or that it wrote nothing
       # @raise [ConsoleCapture::Failure] when the name or adapter is refused, or a file is there
       def converse(**held)
-        require "hecks/cli/interview_run"
-        report = CLI::InterviewRun.call(name: plain(held[:name]), adapter: plain(held[:adapter]), dir: plain(held[:dir]),
-                                        expert: plain(held[:expert]), use_ai: !plain(held[:no_ai]))
+        require "hecks/tools/interview_run"
+        report = Tools::InterviewRun.call(name: plain(held[:name]), adapter: plain(held[:adapter]), dir: plain(held[:dir]),
+                                          expert: plain(held[:expert]), use_ai: !plain(held[:no_ai]))
         { output: { value: report.empty? ? "no interview was written" : report } }
       rescue ArgumentError => e
         raise ConsoleCapture::Failure, e.message
@@ -84,8 +86,8 @@ module Hecks
         if server
           server.call(argv)
         else
-          require "hecks/cli/mcp"
-          CLI::Mcp.call(argv)
+          require "hecks/tools/mcp"
+          Tools::Mcp.call(argv)
         end
       end
 

data/lib/hecks/hecks/adapters/where_reading.adapter

@@ -0,0 +1,7 @@
+# Required by name, not relative to this file: a fuzz or model check boots a copy of this directory,
+# and the implementation must load once, from `lib/`, not from the copy.
+require "hecks/hecks/adapters/where_reading"
+
+Hecks.adapter "WhereReading" do
+  port "Where"
+end

data/lib/hecks/hecks/adapters/where_reading.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "hecks"
+require_relative "settings_reading"
+require_relative "../../adapters/driven/worktree_overlay"
+require_relative "../../adapters/driving/launcher_options"
+
+module Hecks
+  module Adapters
+    # The `Where` port's adapter for `Checkout`: the store each bluebook of a checkout's domain
+    # uses and why, the audience and environment with their reasons, and any overlay file this
+    # worktree lacks. It reads and never writes.
+    class WhereReading
+      # The variable that names the environment a copy runs in.
+      VARIABLE = "HECKS_ENVIRONMENT"
+
+      # Accepts the arguments every driven adapter is built with and keeps none of them.
+      #
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] unused
+      def initialize(aggregate: nil, settings: {}, root: nil); end
+
+      # @param held [Hash] `domain`, a checkout directory (the current directory when absent)
+      # @return [Hash{Symbol => String}] `text:` one line per fact, each with its reason
+      def where(**held)
+        directory = plain(held[:domain]) || Dir.pwd
+        { text: lines(directory).join("\n") }
+      end
+
+      private
+
+      def lines(directory)
+        ["domain: #{directory}", *store_lines(directory), audience_line(directory), environment_line,
+         *missing_line(directory)]
+      end
+
+      def store_lines(directory)
+        SettingsReading.new.stores(directory).map { |label, value, source| "#{label}: #{value} (#{source})" }
+      end
+
+      def audience_line(directory)
+        return "audience: maintainer (a hecks checkout holds this directory)" if Driving::LauncherOptions.maintainer?(directory)
+
+        "audience: person (no hecks checkout holds this directory)"
+      end
+
+      def environment_line
+        return "environment: #{ENV[VARIABLE]} (#{VARIABLE})" if ENV.key?(VARIABLE)
+
+        "environment: default (#{VARIABLE} is not set)"
+      end
+
+      def missing_line(directory)
+        main, files = WorktreeOverlay.gap(directory)
+        return [] if files.empty?
+
+        ["overlay files this worktree lacks: #{files.join(", ")} (from the main checkout at #{main})"]
+      end
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+    end
+  end
+end

data/lib/hecks/hecks/adapters/work_areas.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "area_overlap"
+require_relative "started_work"
+require_relative "console_capture"
+
+module Hecks
+  module Adapters
+    # The `WorkAreas` port's adapter for `Tickets::Work`: says whether a step that was just started
+    # holds ground another started step already holds.
+    #
+    # It reads the other Work rows from the registry it is built with and decides nothing about
+    # the claim beyond the overlap rule in {AreaOverlap}; the bluebook sends a refused step back to
+    # the plan. A step with no area claims nothing and is never refused.
+    class WorkAreas
+      # @param registry [Runtime::Registry, nil] the booted registry whose Work rows are read
+      # @param aggregate [Object, nil] unused
+      def initialize(registry: nil, aggregate: nil)
+        @registry = registry
+      end
+
+      # Clears a started step's area against every other started step's.
+      #
+      # @param held [Hash] the Work row: `work` and `area`
+      # @return [Hash{Symbol => Hash}] `output:` the line that says the area is free
+      # @raise [ConsoleCapture::Failure] naming the row and the overlapping path
+      def check_area(**held)
+        key = plain(held[:work])
+        mine = areas(held[:area])
+        other, pair = mine.empty? ? nil : rival(key, mine)
+        raise ConsoleCapture::Failure, "#{key} cannot claim #{pair[0]}: #{other} holds #{pair[1]}" if other
+
+        { output: { value: "#{key} holds #{mine.empty? ? "no area" : mine.join(", ")}" } }
+      end
+
+      private
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+
+      def areas(list) = Array(list).map { |word| plain(word).to_s }.reject(&:empty?)
+
+      def rival(key, mine)
+        started.each do |row|
+          next if row[:key] == key
+
+          pair = AreaOverlap.first_overlap(mine, row[:area])
+          return [row[:key], pair] if pair
+        end
+        nil
+      end
+
+      def started
+        StartedWork.rows(@registry)
+      end
+    end
+  end
+end