hecks 3.1.0 → 3.1.2

data/lib/hecks/projector/cli_projector.rb

@@ -400,16 +400,15 @@ module Hecks
           return command_help(program, spec[:short], spec, ask: options[:ask]) if spec
         end
 
-        width = (commands.values + questions.values).map { |spec| label(spec).length }.max.to_i
         out = ["#{bluebook.name} — #{bluebook.vision}", "",
                "  #{program} <command>! [name=value …]       do something",
                "  #{program} query <query> [name=value …]    read something", ""]
 
         out << "commands:"
-        out.concat(listing(commands, width) { |spec| spec[:summary] })
+        out.concat(listing(commands) { |spec| spec[:summary] })
         out << ""
         out << "queries (nothing here changes anything):"
-        out.concat(listing(questions, width) { |spec| first_sentence(spec[:summary]) })
+        out.concat(listing(questions) { |spec| first_sentence(spec[:summary]) })
         out << ""
         out << "  #{program} <command> --help       what one command wants, and every way it refuses"
         out << "  a command is called with its aggregate — #{example_qualified(commands)}"
@@ -417,34 +416,59 @@ module Hecks
       end
 
       # The command or question lines of the help. A domain with more than one aggregate is listed
-      # under a heading per aggregate, so related commands sit together; the bookkeeping a run
+      # under a heading per aggregate, so related commands sit together; the heading is the prefix
+      # every call to them carries, so the lines under it leave it out. The bookkeeping a run
       # records about itself (`internal`: system-role commands and port operations) is set apart as
-      # names only, since a person never types them. A single-aggregate domain keeps the plain list.
-      def listing(specs, width)
+      # names only, since a person never types them. A single-aggregate domain keeps the plain
+      # list, each name in full.
+      def listing(specs)
         shown, internal = specs.values.partition { |spec| !spec[:internal] }
         groups = shown.group_by { |spec| spec[:group] }
+        grouped = groups.length > 1
+        named = shown.to_h { |spec| [spec, entry_name(spec, grouped)] }
+        width = named.values.map(&:length).max.to_i
         lines = []
-        if groups.length > 1
+        if grouped
           groups.each do |group, members|
             lines << "  #{heading(group)}" if group
-            members.each { |spec| lines << "    #{label(spec).ljust(width)}  #{yield(spec)}" }
+            members.each { |spec| lines << "    #{named[spec].ljust(width)}  #{yield(spec)}#{alias_note(spec)}" }
           end
         else
-          shown.each { |spec| lines << "  #{label(spec).ljust(width)}  #{yield(spec)}" }
+          shown.each { |spec| lines << "  #{named[spec].ljust(width)}  #{yield(spec)}#{alias_note(spec)}" }
         end
         lines.concat(internal_lines(internal)) unless internal.empty?
         lines
       end
 
-      # "LanguageRun" reads "Language": the Run suffix names the journaled-command shape all of
-      # these aggregates share, so it adds nothing under a heading ("Test suite", "Model check").
+      # The aggregate's own name as a heading: the prefix of every call to the lines under it.
       def heading(group)
-        words = Naming.snake(group.sub(/Run\z/, "")).tr("_", " ")
-        "#{words.capitalize}:"
+        "#{Naming.snake(group)}:"
+      end
+
+      # A spec's name as listed: under its aggregate's heading the aggregate prefix is left out.
+      # A command the chapter gives a short name (`mcp`) is listed by its real name, so the
+      # heading and the line still spell a call; `alias_note` says the short name.
+      def entry_name(spec, grouped)
+        name = label(spec, real: true)
+        return name unless grouped && spec[:group]
+
+        name.delete_prefix("#{Naming.snake(spec[:group])}.")
+      end
+
+      # " (also: mcp!)" for a spec the chapter gave a short name, else nothing. A short name that
+      # is only the command's own name (`init` for `door.init`) is already in the line.
+      def alias_note(spec)
+        return "" if spec[:short_was].nil? || spec[:short_was].split(".").last == spec[:short]
+
+        " (also: #{label(spec)})"
       end
 
       # A command is written with the `!` that marks it; a query without one.
-      def label(spec) = spec[:kind] == :command ? "#{spec[:short]}!" : spec[:short]
+      # With `real:`, a short name the chapter gave it gives way to the name it was given for.
+      def label(spec, real: false)
+        name = real && spec.key?(:short_was) ? spec[:short_was] : spec[:short]
+        spec[:kind] == :command ? "#{name}!" : name
+      end
 
       # The internal commands as bare names, wrapped, under one line saying what they are.
       def internal_lines(specs)

data/lib/hecks/runtime/loader.rb

@@ -50,7 +50,26 @@ module Hecks
       end
 
       # What `describe` answers: the loaded declarations and nothing bound to run them.
-      Described = Struct.new(:registry, :directory)
+      #
+      # The declarations load the first time `registry` is asked for, not when `describe` returns,
+      # so a caller that can answer from `directory` alone (a launcher with its help already
+      # remembered) never pays for the load. The directory is checked at once.
+      class Described
+        # @return [String] the domain directory that was described
+        attr_reader :directory
+
+        # @param directory [String] the domain directory
+        # @yield loads the declarations; answers the registry
+        def initialize(directory, &load)
+          @directory = directory
+          @load = load
+        end
+
+        # @return [Registry] the declarations, loaded on first use
+        def registry
+          @registry ||= @load.call
+        end
+      end
 
       # Loads `path`'s declarations into a fresh Registry and stops: no boot gate runs, no
       # persistence adapter is resolved or bound, nothing connects to a database.
@@ -66,15 +85,19 @@ module Hecks
       def self.describe(path, shared: nil, environment: FROM_ENV)
         loading   = Ports::Loading.bootstrap
         directory = loading.bluebook_directory(path)
-        root      = loading.shared_root(shared, directory)
-        registry  = Registry.new(root: File.dirname(directory))
+        overlay   = selected_environment(environment)
 
-        Hecks.with_registry(registry) do
-          loading.load_library
-          loading.load_project(root)
-          loading.load_domain(directory, environment: selected_environment(environment))
+        Described.new(directory) do
+          root     = loading.shared_root(shared, directory)
+          registry = Registry.new(root: File.dirname(directory))
+
+          Hecks.with_registry(registry) do
+            loading.load_library
+            loading.load_project(root)
+            loading.load_domain(directory, environment: overlay)
+          end
+          registry
         end
-        Described.new(registry, directory)
       end
 
       # The overlay a boot loads: the caller's own choice (nil meaning none), else the

data/lib/hecks/tickets/bluebook/tickets.bluebook

@@ -0,0 +1,331 @@
+# The Tickets chapter: what a maintainer observed about Hecks that needs a decision or a fix, the
+# and the decisions that settle them.
+#
+# QualityControl has its own Ticket, the issue raised for a Bug in an outside tracker, and the
+# Hecks domain has its own Release, the record of a gem version. A Finding sits before both: it is
+# any observation, not yet a proven bug, and it needs no sweep or failing test to be recorded.
+#
+# A Finding is the record. A gap, a parity divergence, a QA finding and an idea are kinds of it, not
+# separate aggregates. Hecks owns the finding's state; GitHub is driven from it through the
+# GitHubIssues port, which a hecksagon binds (nothing here reads GitHub back). A finding exists whether
+# or not GitHub answers: each lifecycle event asks the port, and a refused ask is recorded on the
+# finding as a sync failure that a later run retries.
+#
+# An Adr is a decision record with its own lifecycle, linked to the finding it settles.
+Hecks.bluebook "Tickets" do
+  vision "Track what Hecks needs, decide it, ship it, and drive GitHub from the record."
+
+  aggregate "Finding" do
+    description "One thing observed about Hecks that needs a decision or a fix: reported, triaged, then resolved or dismissed."
+
+    attribute :finding,         FindingKey
+    attribute :title,          Title
+    attribute :body,           Body, optional: true
+    attribute :kind,           Kind, optional: true
+    attribute :severity,       Severity, optional: true
+    attribute :source,         Source
+    attribute :fingerprint,    Fingerprint, optional: true
+    attribute :issue_number,   Number, optional: true
+    attribute :fix_pr_number,  Number, optional: true
+    attribute :dismissal,      Body, optional: true
+    attribute :sync_failure,   Body, optional: true
+    identified_by :finding
+
+    value_object "FindingKey" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+
+      invariant("a finding is named") { !value.to_s.empty? }
+    end
+
+    value_object "Title" do
+      attribute :value, String
+
+      invariant("a finding has a title") { !value.to_s.empty? }
+    end
+
+    value_object "Body" do
+      attribute :value, String
+    end
+
+    # What the finding is: a `gap` Hecks cannot yet express, a `parity` divergence between the Ruby
+    # and Rust runtimes, a `qa` finding from the QA loop, or an `idea`.
+    value_object "Kind" do
+      attribute :value, String, one_of: ["gap", "parity", "qa", "idea"]
+    end
+
+    value_object "Severity" do
+      attribute :value, String, one_of: ["low", "medium", "high"]
+    end
+
+    # Where it came from: the QA loop, work for a client, a parity check, or a maintainer by hand.
+    value_object "Source" do
+      attribute :value, String, one_of: ["qa_loop", "client_work", "parity_check", "maintainer"]
+    end
+
+    # The same finding refiled by the QA loop carries the same fingerprint, so a report of it while an
+    # open finding holds it changes nothing.
+    value_object "Fingerprint" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+    end
+
+    value_object "Number" do
+      attribute :value, Integer
+
+      invariant("a number is positive") { value.positive? }
+    end
+
+    lifecycle :status, default: "reported" do
+      transition "Triage"  => "triaged",   from: %w[reported triaged]
+      transition "Resolve" => "resolved",  from: "triaged"
+      transition "Dismiss" => "dismissed", from: %w[reported triaged]
+      transition "Reopen"  => "triaged",   from: %w[resolved dismissed]
+    end
+
+    command "Report" do
+      goal "Record something observed about Hecks as a finding"
+
+      attribute :finding,      FindingKey
+      attribute :title,       Title
+      attribute :body,        Body, optional: true
+      attribute :source,      Source
+      attribute :fingerprint, Fingerprint, optional: true
+
+      sets :finding
+      sets :title
+      sets :body
+      sets :source
+      sets :fingerprint
+
+      emits "FindingReported"
+    end
+
+    # A failed Codebase run reports itself: the run's key names the finding and doubles as its
+    # fingerprint, so the same run failing again while its finding is open changes nothing.
+    command "ReportFailedRun" do
+      goal "Record a failed conformance or gate run as a finding"
+
+      attribute :finding, FindingKey
+      attribute :body,   Body
+
+      sets :finding
+      sets :body
+      sets :fingerprint, to: "run"
+      sets :title,  to: "A Codebase run failed"
+      sets :source, to: "qa_loop"
+
+      emits "RunFindingReported"
+    end
+
+    command "Triage" do
+      role "Maintainer"
+      goal "Give a finding its kind and severity"
+
+      reference_to Finding
+      attribute :kind,     Kind
+      attribute :severity, Severity
+
+      sets :kind
+      sets :severity
+
+      emits "FindingTriaged"
+    end
+
+    command "LinkFix" do
+      role "Maintainer"
+      goal "Record the pull request that fixes a triaged finding"
+
+      reference_to Finding
+      attribute :fix_pr_number, Number
+
+      sets :fix_pr_number
+
+      emits "FixLinked"
+    end
+
+    command "Resolve" do
+      role "Maintainer"
+      goal "Close a triaged finding as resolved"
+
+      reference_to Finding
+
+      emits "FindingResolved"
+    end
+
+    command "Dismiss" do
+      role "Maintainer"
+      goal "Close a finding without a fix, with the reason"
+
+      reference_to Finding
+      attribute :dismissal, Body
+
+      sets :dismissal
+
+      emits "FindingDismissed"
+    end
+
+    command "Reopen" do
+      role "Maintainer"
+      goal "Take a resolved or dismissed finding back to triaged, as when a fix regresses"
+
+      reference_to Finding
+
+      emits "FindingReopened"
+    end
+
+    command "RecordIssue" do
+      goal "Record the GitHub issue number once the issue is opened"
+
+      reference_to Finding
+      attribute :issue_number, Number
+
+      sets :issue_number
+
+      emits "IssueRecorded"
+    end
+
+    command "RecordSyncFailure" do
+      goal "Record that GitHub could not be driven, so a later run retries"
+
+      reference_to Finding
+      attribute :sync_failure, Body
+
+      sets :sync_failure
+
+      emits "SyncFailed"
+    end
+
+    query "Open" do
+      description "Every finding not yet resolved or dismissed."
+      where(status: { in: "reported,triaged" })
+      order_by :finding
+    end
+  end
+
+  aggregate "Adr" do
+    description "A decision record: drafted, accepted, and possibly superseded, linked to the tickets it settles."
+
+    attribute :adr,       AdrNumber
+    attribute :title,     AdrTitle
+    attribute :supersedes, AdrNumber, optional: true
+    attribute :settles,   FindingKey, optional: true
+    identified_by :adr
+
+    value_object "AdrNumber" do
+      attribute :value, String, pattern: '\A[0-9]{4}\z'
+    end
+
+    value_object "AdrTitle" do
+      attribute :value, String
+
+      invariant("a decision has a title") { !value.to_s.empty? }
+    end
+
+    value_object "FindingKey" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+    end
+
+    lifecycle :status, default: "draft" do
+      transition "Accept"    => "accepted",   from: "draft"
+      transition "Supersede" => "superseded", from: "accepted"
+    end
+
+    command "Draft" do
+      role "Maintainer"
+      goal "Open a decision record, optionally for the finding it settles"
+
+      attribute :adr,       AdrNumber
+      attribute :title,     AdrTitle
+      attribute :settles,   FindingKey, optional: true
+
+      sets :adr
+      sets :title
+      sets :settles
+
+      emits "AdrDrafted"
+    end
+
+    command "Accept" do
+      role "Maintainer"
+      goal "Record that the decision was accepted"
+
+      reference_to Adr
+
+      emits "AdrAccepted"
+    end
+
+    command "Supersede" do
+      role "Maintainer"
+      goal "Record that a later decision replaces this one"
+
+      reference_to Adr
+      attribute :supersedes, AdrNumber
+
+      sets :supersedes
+
+      emits "AdrSuperseded"
+    end
+
+    query "Standing" do
+      description "Every decision that is accepted and not superseded."
+      where(status: "accepted")
+      order_by :adr
+    end
+  end
+
+  # Each lifecycle event drives GitHub. A finding's own state never waits on the answer.
+  policy "OpenIssueWhenReported" do
+    on      "Finding.FindingReported"
+    trigger Finding::GitHubIssues::OpenIssue, with: { finding: :finding }
+  end
+
+  policy "OpenIssueWhenRunReported" do
+    on      "Finding.RunFindingReported"
+    trigger Finding::GitHubIssues::OpenIssue, with: { finding: :finding }
+  end
+
+  policy "LabelIssueWhenTriaged" do
+    on      "Finding.FindingTriaged"
+    trigger Finding::GitHubIssues::LabelIssue, with: { finding: :finding }
+  end
+
+  policy "CommentWhenFixLinked" do
+    on      "Finding.FixLinked"
+    trigger Finding::GitHubIssues::CommentOnIssue, with: { finding: :finding }
+  end
+
+  policy "CloseIssueWhenResolved" do
+    on      "Finding.FindingResolved"
+    trigger Finding::GitHubIssues::CloseIssue, with: { finding: :finding }
+  end
+
+  policy "CloseIssueWhenDismissed" do
+    on      "Finding.FindingDismissed"
+    trigger Finding::GitHubIssues::CloseIssue, with: { finding: :finding }
+  end
+
+  policy "ReopenIssueWhenReopened" do
+    on      "Finding.FindingReopened"
+    trigger Finding::GitHubIssues::ReopenIssue, with: { finding: :finding }
+  end
+
+  # A conformance or gate run that faults files its own finding.
+  policy "ReportWhenConformanceFaulted" do
+    on      "ConformanceRun.ConformanceFaulted"
+    trigger Finding::ReportFailedRun, with: { finding: :run, body: :refusal }
+  end
+
+  policy "ReportWhenGateFaulted" do
+    on      "GateRun.GateFaulted"
+    trigger Finding::ReportFailedRun, with: { finding: :run, body: :refusal }
+  end
+
+  policy "RecordTheIssue" do
+    on      "Finding.IssueOpened"
+    trigger Finding::RecordIssue, with: { issue_number: :issue_number }
+  end
+
+  policy "RecordTheSyncFailure" do
+    on      "Finding.GitHubRefused"
+    trigger Finding::RecordSyncFailure, with: { sync_failure: :refusal }
+  end
+end

data/lib/hecks/tickets/bluebook/tickets.hecksagon

@@ -0,0 +1,11 @@
+# The Tickets domain, bound so it boots standing alone (a fuzz or model_check boot of this
+# directory). The GitHubIssues port every attaching hecksagon shares is in tickets.ports.hecksagon.
+Hecks.hecksagon "Tickets" do
+  attaches "Governance"
+  persisted_by "Memory"
+end
+
+# The anti-corruption layer for Governance, which the chapter's roles are checked against.
+Hecks.hecksagon "Governance" do
+  persisted_by "Memory"
+end

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

@@ -0,0 +1,26 @@
+# The port Tickets declares, for every hecksagon that attaches the chapter (`Chapters` loads this
+# file with it). Each lifecycle event of a finding asks the GitHubIssues port, which the Hecks domain
+# binds (lib/hecks/hecks/adapters/finding_github.rb): the outside a finding reaches. The ask is
+# answered with the record's own arguments or refused with a reason, and a refusal is recorded on the
+# finding and never blocks it. The port has to be declared even where no adapter binds it, so the
+# policies have a target and model_check's deaf-policy check can see it.
+#
+# Only OpenIssue answers with the issue number, so only its answer is recorded on the finding; the
+# other asks answer with a line saying what was done.
+Hecks.hecksagon "Tickets" do
+  Tickets::Finding.port "GitHubIssues" do
+    asks "OpenIssue", to: Finding do
+      attribute :finding, FindingKey
+      answers "IssueOpened"
+      refuses "GitHubRefused"
+    end
+
+    %w[LabelIssue CommentOnIssue CloseIssue ReopenIssue].each do |ask|
+      asks ask, to: Finding do
+        attribute :finding, FindingKey
+        answers "GitHubAnswered"
+        refuses "GitHubRefused"
+      end
+    end
+  end
+end

data/lib/hecks/version.rb

@@ -1,5 +1,5 @@
 module Hecks
   # Read directly by the gemspec, so this file must never require the
   # rest of the gem (its dependencies aren't resolved yet at that point).
-  VERSION = "3.1.0".freeze
+  VERSION = "3.1.2".freeze
 end

data/lib/hecks.rb

@@ -29,6 +29,7 @@ require_relative "hecks/projector"
 require_relative "hecks/projections"
 # After `Projector`, which dispatches against the `:cli` projection.
 require_relative "hecks/doors/cli_door"
+require_relative "hecks/doors/usage_cache"
 require_relative "hecks/doors/cli_runner"
 require_relative "hecks/storehouse"
 require_relative "hecks/mcp_stdio_guard"

data/rust/codegen/src/commands.rs

@@ -444,14 +444,7 @@ pub fn emit_command(exemplar: &Exemplar, command: &Json, aggregate: &Json, domai
         .collect();
 
     let transition = mutations::lifecycle_transition_for(command, aggregate);
-    let transition_arg = match &transition {
-        Some(t) => format!(
-            "Some(crate::kernel::TransitionCheck {{ field: {}, from_states: &[{}] }})",
-            naming::ruby_inspect_string(&t.field),
-            t.from_states.iter().map(|s| naming::ruby_inspect_string(s)).collect::<Vec<_>>().join(", ")
-        ),
-        None => "None".to_string(),
-    };
+    let transition_arg = mutations::transition_check_arg(transition.as_ref());
 
     let mutations_list = command.get("mutations").map(Json::each).unwrap_or(&[]);
     // A `delegate` mutation is rendered by `delegation_of`, which overwrites `mutation_lines`;
@@ -772,14 +765,7 @@ fn delegation_of(exemplar: &Exemplar, command: &Json, aggregate: &Json, value_ob
         })
         .collect();
     let transition = mutations::lifecycle_transition_for(target, entity);
-    let transition_arg = match &transition {
-        Some(t) => format!(
-            "Some(crate::kernel::TransitionCheck {{ field: {}, from_states: &[{}] }})",
-            naming::ruby_inspect_string(&t.field),
-            t.from_states.iter().map(|s| naming::ruby_inspect_string(s)).collect::<Vec<_>>().join(", ")
-        ),
-        None => "None".to_string(),
-    };
+    let transition_arg = mutations::transition_check_arg(transition.as_ref());
     let mut mutation_lines: Vec<String> = target
         .get("mutations")
         .map(Json::each)
@@ -896,14 +882,7 @@ pub fn emit_entity_command(
         .collect();
 
     let transition = mutations::lifecycle_transition_for(command, entity);
-    let transition_arg = match &transition {
-        Some(t) => format!(
-            "Some(crate::kernel::TransitionCheck {{ field: {}, from_states: &[{}] }})",
-            naming::ruby_inspect_string(&t.field),
-            t.from_states.iter().map(|s| naming::ruby_inspect_string(s)).collect::<Vec<_>>().join(", ")
-        ),
-        None => "None".to_string(),
-    };
+    let transition_arg = mutations::transition_check_arg(transition.as_ref());
 
     let mutations_list = command.get("mutations").map(Json::each).unwrap_or(&[]);
     let mut mutation_lines: Vec<String> = mutations_list.iter().map(|m| mutations::emit_mutation_line(exemplar, m, entity, command, value_objects_by_name, false)).collect();
@@ -1063,14 +1042,7 @@ pub fn emit_nested_entity_command(
 
     // The nested entity's lifecycle, as in `emit_entity_command`.
     let transition = mutations::lifecycle_transition_for(command, nested);
-    let transition_arg = match &transition {
-        Some(t) => format!(
-            "Some(crate::kernel::TransitionCheck {{ field: {}, from_states: &[{}] }})",
-            naming::ruby_inspect_string(&t.field),
-            t.from_states.iter().map(|s| naming::ruby_inspect_string(s)).collect::<Vec<_>>().join(", ")
-        ),
-        None => "None".to_string(),
-    };
+    let transition_arg = mutations::transition_check_arg(transition.as_ref());
 
     let mutations_list = command.get("mutations").map(Json::each).unwrap_or(&[]);
     let mut mutation_lines: Vec<String> = mutations_list.iter().map(|m| mutations::emit_mutation_line(exemplar, m, nested, command, value_objects_by_name, false)).collect();

data/rust/codegen/src/json_codec.rs

@@ -44,6 +44,7 @@ pub fn scalar_json_accessor(scalar_type: &str) -> &'static str {
         "String" => "as_str",
         "Integer" => "as_i64",
         "Float" => "as_f64",
+        "TrueClass" | "FalseClass" => "as_bool",
         other => panic!("no JSON accessor for scalar type {other:?}"),
     }
 }
@@ -77,6 +78,7 @@ pub fn scalar_to_json_expr(scalar_type: &str, rust_expr: &str) -> String {
         "String" => format!("crate::kernel::Json::Str({rust_expr}.clone())"),
         "Integer" => format!("crate::kernel::Json::int({rust_expr})"),
         "Float" => format!("crate::kernel::Json::Float({rust_expr})"),
+        "TrueClass" | "FalseClass" => format!("crate::kernel::Json::Bool({rust_expr})"),
         other => panic!("no to_json expr for scalar type {other:?}"),
     }
 }
@@ -565,6 +567,7 @@ pub fn emit_closed_set_table_codec(exemplar: &Exemplar, vo: &Json) -> String {
                 Some("String") => format!("crate::kernel::Json::Str(self.{ident}.to_string())"),
                 Some("Integer") => format!("crate::kernel::Json::int(self.{ident})"),
                 Some("Float") => format!("crate::kernel::Json::Float(self.{ident})"),
+                Some("TrueClass" | "FalseClass") => format!("crate::kernel::Json::Bool(self.{ident})"),
                 _ => String::new(),
             };
             exemplar.render("to_json_field", &[("\"tmpl_field_name\"", naming::ruby_inspect_string(&key)), ("tmpl_json_value_placeholder()", value_expr)])