hecks 3.10.0 → 3.12.0

data/lib/hecks/hecks/adapters/rehearsal/rust_audit.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "hecks/projector/exporter"
+
+module Hecks
+  module Adapters
+    module Rehearsal
+      # The Rust host's mint audit (`reference_validate`), run over the translated rows through the
+      # `validate_harness` binary, as the second engine of a rehearsal.
+      #
+      # The binary is found by `HECKS_VALIDATE_HARNESS`, else under `rust/host/target` of the
+      # checkout this gem runs from (`cargo build --bin validate_harness`); a rehearsal never
+      # builds it. Without one the engine is reported as not run.
+      class RustAudit
+        # @!attribute [r] ran
+        #   @return [Boolean] whether the harness answered
+        # @!attribute [r] violations
+        #   @return [Array<String>] its refusals, `Aggregate#id: wording`
+        # @!attribute [r] note
+        #   @return [String] why it did not run, or what it ran over
+        # @!attribute [r] rows
+        #   @return [Integer] how many rows it was given (zero when it did not run)
+        Result = Struct.new(:ran, :violations, :note, :rows, keyword_init: true)
+
+        # @return [String, nil] the harness binary, when one stands
+        def self.binary
+          root = File.expand_path("../../../../..", __dir__)
+          built = %w[debug release].map { |profile| "#{root}/rust/host/target/#{profile}/validate_harness" }
+          [ENV.fetch("HECKS_VALIDATE_HARNESS", nil), *built].compact.find { |path| File.executable?(path) }
+        end
+
+        # @param subject [Subject] the loaded domain, whose IR the audit is held to
+        # @param states [Hash{String => Hash{String => Hash}}] aggregate name, then id, then state
+        # @return [Result] what the harness refused, or why it did not run
+        def self.call(subject, states)
+          path = binary
+          return new(nil, subject).stood_down("no validate_harness built: cargo build --bin validate_harness") unless path
+
+          new(path, subject).call(states)
+        end
+
+        # @param path [String, nil] the harness binary
+        # @param subject [Subject] the loaded domain
+        def initialize(path, subject)
+          @path = path
+          @subject = subject
+        end
+
+        # @param states [Hash] aggregate name, id, state
+        # @return [Result] the harness's answer
+        def call(states)
+          cases = states.flat_map { |name, rows| rows.map { |id, state| case_for(name, id, state) } }
+          out, err, status = Open3.capture3(@path, stdin_data: JSON.generate("ir" => ir, "cases" => cases))
+          return stood_down("validate_harness failed: #{err.lines.first&.strip}") unless status.success?
+
+          answered(out, cases.size)
+        end
+
+        # @param note [String] why the engine did not run
+        # @return [Result] an answer that refused nothing
+        def stood_down(note) = Result.new(ran: false, violations: [], note: note, rows: 0)
+
+        private
+
+        def answered(out, rows)
+          Result.new(ran: true, violations: refusals(out), note: "ran over #{rows} rows", rows: rows)
+        end
+
+        def ir = Projector::Exporter.call(@subject.held.registry).fetch(@subject.bluebook.name)
+
+        def case_for(name, id, state)
+          { "aggregate" => name, "id" => id, "state" => JSON.parse(JSON.generate(state)) }
+        end
+
+        def refusals(out)
+          JSON.parse(out).fetch("results").flat_map { |result| result["violations"] || [result["error"]].compact }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/rehearsal/subject.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require_relative "declaration"
+require_relative "environment"
+require_relative "../journal_store/edge_audit"
+require_relative "../journal_store/held_domain"
+
+module Hecks
+  module Adapters
+    module Rehearsal
+      # The domain a rehearsal is run on: loaded as the era tools load it, with nothing bound or
+      # booted, so no persistence binding of the domain's own is reached.
+      class Subject
+        # The domain did not load: the answer a rehearsal gives is `cannot_boot`, with the reason.
+        class CannotBoot < StandardError; end
+
+        attr_reader :held, :declaration, :environment
+
+        # @param path [String] the domain directory
+        # @return [Subject] the loaded subject, with its world's declaration checked
+        # @raise [CannotBoot] if the directory is absent, declares no bluebook or does not load
+        # @raise [Refused] if the world's `rehearsed_by` is absent or wrong
+        def self.open(path)
+          environment = choose_environment(path)
+          held = load(path, environment)
+          new(held, Declaration.from_world(held.registry.world(held.bluebook.name), held.directory), environment)
+        end
+
+        # Whatever stops a domain from loading is a reason it cannot boot, a script error included.
+        # A missing bind names the environment that was loaded and the file it came from.
+        #
+        # @api private
+        def self.load(path, environment)
+          JournalStore::HeldDomain.open(path, environment: environment.overlay)
+        rescue Runtime::WiringError => e
+          raise CannotBoot, "#{e.message} The rehearsal loaded #{environment}; overlays this domain " \
+                            "holds: #{environment.available_words}. " \
+                            "Name one with `environment \"...\"` in rehearsed_by, or HECKS_PROJECT_ENVIRONMENT."
+        rescue StandardError, ScriptError => e
+          raise CannotBoot, e.message
+        end
+        private_class_method :load
+
+        # The overlay the world names, read before the domain loads so the load can use it.
+        #
+        # @api private
+        def self.choose_environment(path)
+          loading = Ports::Loading.bootstrap
+          directory = loading.bluebook_directory(path)
+          Environment.resolve(declared_environment(loading, directory), directory)
+        rescue StandardError, ScriptError
+          Environment.resolve(nil, path.to_s)
+        end
+        private_class_method :choose_environment
+
+        # @api private
+        def self.declared_environment(loading, directory)
+          registry = Runtime::Registry.new(root: File.dirname(directory))
+          Hecks.with_registry(registry) do
+            loading.load_library
+            loading.load_each(directory, %w[*.world])
+          end
+          registry.worlds.values.filter_map { |world| world.for_verb("rehearsed_by")[:environment] }.first
+        rescue StandardError, ScriptError
+          nil
+        end
+        private_class_method :declared_environment
+
+        # @param held [JournalStore::HeldDomain] the loaded domain
+        # @param declaration [Declaration] what its world says about the data copy
+        # @param environment [Environment] the overlay the domain was loaded under
+        def initialize(held, declaration, environment)
+          @held = held
+          @declaration = declaration
+          @environment = environment
+        end
+
+        # @return [Bluebook::Chapter] the domain's bluebook as it stands
+        def bluebook = held.bluebook
+
+        # @return [String] the label the shape a mint would hold has
+        def label = Runtime::StorageShape.mint_label(bluebook)
+
+        # @return [String] the domain's bluebook directory
+        def directory = held.directory
+
+        # The edge that leads one era's label to the shape's label.
+        #
+        # @param from [String] the held era's label
+        # @return [Bluebook::Translation, nil] the edge; nil when none is declared
+        def edge_from(from)
+          held.registry.translations.find { |t| t.domain == bluebook.name && t.from == from && t.to == label }
+        end
+
+        # @return [Array<String>] the persisted databases the domain's own world names, which a
+        #   rehearsal must never be pointed at
+        def declared_databases
+          blocks = held.registry.world(bluebook.name)&.settings || {}
+          blocks.select { |key, _| key.to_s.start_with?("persisted_by") }.values.filter_map { |block| block[:database] }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/rehearsal.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "open3"
+require_relative "rehearsal/declaration"
+require_relative "rehearsal/rows"
+require_relative "rehearsal/subject"
+require_relative "rehearsal/memory_store"
+require_relative "rehearsal/postgres_store"
+require_relative "rehearsal/inquiry"
+
+module Hecks
+  module Adapters
+    # Helpers the two rehearsal port adapters (`RehearsalStore`, `RehearsalSubject`) share.
+    module Rehearsal
+      module_function
+
+      # The Hecks this process runs, as `release+commit` when a checkout can name its commit.
+      #
+      # @return [String] `3.9.0`, or `3.9.0+bb8e41d`
+      def host_version
+        commit = checkout_commit
+        commit ? "#{Hecks::VERSION}+#{commit[0, 7]}" : Hecks::VERSION.to_s
+      end
+
+      # @param pin [String, nil] a release or a commit prefix the run must be on
+      # @return [void]
+      # @raise [Refused] if this process is not on the pin
+      def check_pin!(pin)
+        return if pin.nil? || pin.empty? || pin == Hecks::VERSION.to_s || checkout_commit.to_s.start_with?(pin)
+
+        raise Refused, "this is Hecks #{host_version}, not the pin #{pin}: run the rehearsal from the pinned install"
+      end
+
+      # @param subject [Subject] the loaded domain
+      # @param run [String] the rehearsal's key
+      # @return [MemoryStore, PostgresStore] the store its world declares
+      def store_for(subject, run)
+        declaration = subject.declaration
+        return MemoryStore.new(declaration) if declaration.kind == "memory"
+
+        PostgresStore.new(declaration, run, protected_databases: subject.declared_databases)
+      end
+
+      # @return [String, nil] the commit of the checkout this gem runs from
+      def checkout_commit
+        root = File.expand_path("../../../..", __dir__)
+        out, status = Open3.capture2("git", "-C", root, "rev-parse", "HEAD", err: File::NULL)
+        status.success? ? out.strip : nil
+      rescue SystemCallError
+        nil
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/rehearsal_store.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/rehearsal_store"
+
+Hecks.adapter "RehearsalStore" do
+  port "RehearsalStore"
+end

data/lib/hecks/hecks/adapters/rehearsal_store.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative "rehearsal"
+
+module Hecks
+  module Adapters
+    # The `RehearsalStore` port's adapter: the copy of a domain's data its own world names, which
+    # prepares itself when surveyed, runs the mint's audit over itself when examined, and is
+    # dropped when it has answered, whichever way it answers.
+    #
+    # The strategy (`memory` or `postgres`) is the one the subject's `.world` declares with
+    # `rehearsed_by`, never an argument. Nothing is written to the subject's own databases: no era
+    # is held or named, no table provisioned, no command dispatched. The copy is dropped here, in
+    # the same ask that last needs it, so no reaction that fails to arrive can leave one behind.
+    class RehearsalStore
+      # 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
+
+      # Prepares the copy, loads the domain against it, and reads where its shape stands.
+      #
+      # @param held [Hash] the record: `domain`, `run` and `pin`
+      # @return [Hash] the shape facts and what the copy holds, or `booted: false` with why the
+      #   domain did not load
+      # @raise [Rehearsal::Refused] if the pin, the world's declaration or the copy is refused
+      def survey(**held)
+        Rehearsal.check_pin!(plain(held[:pin]))
+        subject = Rehearsal::Subject.open(plain(held[:domain]))
+        store = Rehearsal.store_for(subject, plain(held[:run]))
+        store.prepare!
+        guarded(store) { surveyed(subject, store) }
+      rescue Rehearsal::Subject::CannotBoot => e
+        { booted: { value: false }, boot_error: { value: e.message } }
+      end
+
+      # Runs the mint's audit over the copy, then drops it.
+      #
+      # @param held [Hash] the record: `domain` and `run`
+      # @return [Hash] the edge facts, every refused row, what was not checked, and whether the
+      #   copy was dropped
+      def examine(**held)
+        subject = Rehearsal::Subject.open(plain(held[:domain]))
+        store = Rehearsal.store_for(subject, plain(held[:run]))
+        facts = guarded(store) { Rehearsal::Inquiry.new(subject, store).examine }
+        facts.merge(release(store))
+      rescue Rehearsal::Subject::CannotBoot => e
+        raise Rehearsal::Refused, e.message
+      end
+
+      private
+
+      # A copy that holds nothing is answered at once, so it is dropped here: no examination
+      # follows to drop it. Any other copy stands until it is examined.
+      def surveyed(subject, store)
+        facts = Rehearsal::Inquiry.new(subject, store).survey
+        standing = { released: { value: false }, kept: { value: "" } }
+        facts.merge(facts[:copy_empty][:value] ? release(store) : standing)
+      end
+
+      # Runs the block; when it raises, the copy is dropped before the error goes on.
+      def guarded(store)
+        yield
+      rescue StandardError
+        release(store)
+        raise
+      end
+
+      def release(store)
+        store.drop!
+        { released: { value: true }, kept: { value: "" } }
+      rescue Rehearsal::Refused, StandardError => e
+        { released: { value: false }, kept: { value: e.message } }
+      end
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+    end
+  end
+end

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

@@ -6,7 +6,7 @@ require "hecks/cli/console"
 module Hecks
   module Adapters
     # The `Terminal` port's adapter: the sessions an operator or a program drives through stdin and
-    # stdout, an IRB console (`open`) or the stdio MCP door (`serve`).
+    # stdout, an IRB console (`open`) or the stdio MCP server (`serve`).
     #
     # The journal records that a session was opened and how it ended, not what was said in it.
     # Each starts here and nowhere else; a caller that must not open a real session (a spec)
@@ -43,26 +43,28 @@ module Hecks
         { output: { value: "console session ended (#{domain || "pizzas"})" } }
       end
 
-      # Hands the process over to the MCP door until the client closes stdin. The door writes its
+      # Hands the process over to the MCP server until the client closes stdin. The server writes
+      # its
       # JSON-RPC on stdout, so nothing here is captured, and the launcher's own answer follows
       # only once the client is gone.
       #
-      # @param held [Hash] the `Door` record: `stdio` (whether `--stdio` was given)
-      # @return [Hash{Symbol => Hash}] `output:` a one-line note that the door closed
-      # @raise [ConsoleCapture::Failure] when the process is not set up for stdio: the door
+      # @param held [Hash] the `Launch` record: `stdio` (whether `--stdio` was given)
+      # @return [Hash{Symbol => Hash}] `output:` a one-line note that the server closed
+      # @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_door(plain(held[:stdio]) ? ["--stdio"] : [])
+        run_server(plain(held[:stdio]) ? ["--stdio"] : [])
 
-        { output: { value: "mcp door closed" } }
+        { output: { value: "mcp server closed" } }
       rescue SystemExit => e
-        raise ConsoleCapture::Failure, "the mcp door refused to start (status #{e.status}); see stderr"
+        raise ConsoleCapture::Failure, "the mcp server refused to start (status #{e.status}); see stderr"
       end
 
       # Holds an interview at the terminal and writes the domain it drafts (ADR 0088). Asking is IO,
       # so it happens here and nowhere else; the journal records that one was held, not its words.
       #
-      # @param held [Hash] the `Door` record: `name`; optionally `adapter`, `dir`, `expert`, `no_ai`
+      # @param held [Hash] the `Launch` record: `name`; optionally `adapter`, `dir`, `expert`,
+      #   `no_ai`
       # @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)
@@ -76,8 +78,8 @@ module Hecks
 
       private
 
-      # Hands the process to the server a spec set, or else to the real MCP door.
-      def run_door(argv)
+      # Hands the process to the server a spec set, or else to the real MCP server.
+      def run_server(argv)
         server = self.class.server
         if server
           server.call(argv)

data/lib/hecks/hecks/codebase.behaviors

@@ -1,7 +1,7 @@
 Hecks.behaviors "Codebase" do
   vision "A request to work on this repository is recorded, the tree is examined, and only a hecks checkout lets it through."
 
-  loads "hecks.bluebook", "custodian.bluebook", "codebase.bluebook", "context_map.hecksagon", "hecks.hecksagon", "environments/memory.world"
+  loads "hecks.bluebook", "custodian.bluebook", "tooling.bluebook", "rehearsal.bluebook", "codebase.bluebook", "context_map.hecksagon", "hecks.hecksagon", "environments/memory.world"
 
   test "ProjectModel reports what the language projects, and keeps the answer" do
     tests "ProjectModel", on: "LanguageRun"
@@ -187,4 +187,16 @@ Hecks.behaviors "Codebase" do
     input run: { value: "" }
     expect refused: "must match"
   end
+
+  test "Flog refuses a list of paths that is not one" do
+    tests "Flog", on: "InspectionRun"
+    input paths: { value: "lib, spec" }, run: { value: "paths" }
+    expect refused: "must match"
+  end
+
+  test "Reek refuses a count that is not positive" do
+    tests "Reek", on: "InspectionRun"
+    input top: { value: 0 }, run: { value: "top" }
+    expect refused: "positive"
+  end
 end