hecks 3.0.4 → 3.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 90a718a197fae0287e4fe16033540bf625166bc31bfb3482e0752d1039a2a949
-  data.tar.gz: 15fe27abd9a488dfe4f579118f8e8ffbea1302b956ee36fbd2b9475eb3b88429
+  metadata.gz: 16dca2d33433ad6c6cd98b8dee40f652df3d84c7bb93df5cd1f7734b99542c08
+  data.tar.gz: '084b92e2ad954b89a488d44997d754cd15388136f502f918f24274fd26cf9e87'
 SHA512:
-  metadata.gz: d74d07807e22e8899c041adfa96d799b5eb47713a0dec6c05bbb9e61a579a32a35da890b67aaf876b1ba5182e0961a112f370e0e04adcf2719f8ae57a50cfd45
-  data.tar.gz: 11e85c77dc6a4f5d34ec3acd54e41873be8d03b980e4ef97a8d0d7c9da4b63ecfc2b04e2a1322f8c1536ad1d58f8f85f50df2ca58f3d6fea44126cb871c05b0d
+  metadata.gz: 0f2b6dda10ee042c6cb1bbe3ae9100a66c35dad25b17a031ab7ca6fd0eaf7ea5960b1a3e52024d5a40c3090ca999f1730db9275f7a5ec8b803e8ae0a465102df
+  data.tar.gz: 8aebabbb0a023e9c2ff989df18f665924ec9acf4043a922bcb995588fb424683d8d44bea2e02f2076932beae2b27d63da097153c054131aa4232c132123d33eb

data/exe/hecks

@@ -21,6 +21,11 @@ if LEGACY.include?(ARGV.first)
   exit Hecks::CLI.start(ARGV) unless Hecks::CLI.launcher_form?(ARGV)
 end
 
+# These verbs keep nothing worth a database, so they run on Memory unless told otherwise, and
+# print nothing when they end well.
+MEMORY_VERBS = %w[console].freeze
+ENV["HECKS_ENVIRONMENT"] ||= "memory" if MEMORY_VERBS.include?(ARGV.first)
+
 require "hecks"
 
 # Usage is answered from the projected chapter alone: no adapter is bound and no
@@ -39,7 +44,7 @@ text, status, reason = Hecks::Doors::CliRunner.usage(
 )
 unless text
   runtime = begin
-    Hecks.boot_described(described, install_doors: false)
+    Hecks::Doors::LauncherOptions.quietly(hold: MEMORY_VERBS.include?(ARGV.first)) { Hecks.boot_described(described, install_doors: false) }
   rescue StandardError => e
     abort "cannot open Hecks: #{e.message.lines.first.strip}"
   end
@@ -57,4 +62,5 @@ if reason
   warn reason
   exit status
 end
+exit 0 if status.zero? && MEMORY_VERBS.include?(ARGV.first)
 status.zero? ? puts(text) : abort(text)

data/lib/hecks/cli/console.rb

@@ -9,7 +9,7 @@ module Hecks
     # The command behind `hecks console` and Custodian's `Operation.OpenConsole`: boots a domain
     # (pizzas on Memory by default) and drops into IRB with its door installed, for dispatching a
     # real command by hand. No argument needs no database (ADR 0073); a domain directory boots as
-    # it is wired, which may bind PostgresEra.
+    # it is wired, which may bind PostgresEra (examples/directory does).
     module Console
       PIZZAS = File.expand_path("../../../examples/pizzas", __dir__)
 
@@ -25,14 +25,27 @@ module Hecks
       # @param domain [String, nil] a domain directory; the bundled pizzas domain when nil
       # @param launcher [#call] starts the interactive session; IRB unless a caller stands in
       # @return [Runtime] the runtime the session ran against
-      def call(domain = nil, launcher: -> { IRB.start(__FILE__) })
+      def call(domain = nil, launcher: -> { irb_session })
         runtime = domain ? Hecks.boot(domain) : Hecks.boot_files(DEFAULT_FILES)
         puts overview(runtime)
-        puts banner
+        puts banner(domain)
         launcher.call
         runtime
       end
 
+      # Starts IRB with an empty command line. IRB reads `ARGV` for a script to run, and a
+      # launcher's `ARGV` holds its own words (`console`, `subject=<domain>`), which IRB would
+      # open as a file and then exit without a prompt.
+      #
+      # @return [void] when the session ends; `ARGV` is restored
+      def irb_session
+        words = ARGV.dup
+        ARGV.clear
+        IRB.start(__FILE__)
+      ensure
+        ARGV.replace(words)
+      end
+
       # @param runtime [Runtime] a booted domain
       # @return [String] each chapter's vision and its aggregates' commands
       def overview(runtime)
@@ -46,16 +59,19 @@ module Hecks
         end.join
       end
 
-      # @return [String] the version and a first session to try against the pizzas domain
-      def banner
+      # @param domain [String, nil] a domain directory, or nil for the bundled pizzas domain
+      # @return [String] the version, and for the pizzas domain a first session to try
+      def banner(domain = nil)
+        return "\nhecks #{Hecks::VERSION}\n\n" if domain
+
         <<~BANNER
 
           hecks #{Hecks::VERSION}
 
           try:
-            order = Order.create_pizza!(name: { value: "Margherita" }, pizza: { price_cents: { cents: 1200 }, size: { value: "large" } })
-            order.add_topping!(topping: { value: "Basil" }, amount: { value: 3 })
-            order.purchase!(customer_name: { value: "Chris" }, amount: { cents: 1200 })
+            order = Order.create_pizza!(name: "Margherita", pizza: { price_cents: { cents: 1200 }, size: "large" })
+            order.add_topping!(topping: "Basil", amount: 3)
+            order.purchase!(customer_name: "Chris", amount: { cents: 1200 })
             order.status
             order.events.last
 

data/lib/hecks/cli/project_cli.rb

@@ -103,7 +103,7 @@ module Hecks
         label      = executable || "#{path}/#{snake}"
         file       = File.join(root, label)
         text       = launcher(path, name, program, executable: executable, legacy: setting[:legacy],
-                          opted: !setting.empty?)
+                          memory_verbs: setting[:memory_verbs], opted: !setting.empty?)
         return skip(path, "#{label} is a directory") if File.directory?(file)
 
         return :drifted if check && !(File.file?(file) && File.read(file) == text)
@@ -150,10 +150,11 @@ module Hecks
       # @param executable [String, nil] the file's path under the root when it is not beside the
       #   domain; its program name is then that file's basename, and its header names the generator
       # @param legacy [Array<String>, nil] verbs an executable hands to `Hecks::CLI` first
+      # @param memory_verbs [Array<String>, nil] verbs run on Memory unless HECKS_ENVIRONMENT is set
       # @param opted [Boolean] whether the chapter's world declares a `launcher` setting
       # @return [String] the Ruby source
       # @raise [ArgumentError] if a name, path, executable or legacy verb is not plain
-      def launcher(path, name, program, executable: nil, legacy: nil, opted: !executable.nil?)
+      def launcher(path, name, program, executable: nil, legacy: nil, memory_verbs: nil, opted: !executable.nil?)
         plain!("chapter name", name, NAME)
         plain!("domain path", path, PATH)
         snake = Naming.snake(name)
@@ -174,9 +175,10 @@ module Hecks
           where = shown = "#{path}/#{snake}"
         end
 
-        handoff  = legacy_handoff(Array(legacy)) if executable
+        handoff  = legacy_handoff(Array(legacy)) + memory_default(Array(memory_verbs)) if executable
         encoding = opted ? ENCODING : ""
         ending   = opted ? OPTED_ENDING : PLAIN_ENDING
+        ending   = quiet_ending(ending) if executable && !Array(memory_verbs).empty?
 
         <<~RUBY
           #!/usr/bin/env ruby
@@ -194,7 +196,7 @@ module Hecks
           #{handoff}
           require "hecks"
 
-          #{entry(name, boot, shown, opted)}
+          #{entry(name, boot, shown, opted, quiet: !Array(memory_verbs).empty?)}
           #{ending}
         RUBY
       end
@@ -203,13 +205,15 @@ module Hecks
       # @return [String] the launcher's middle: for an opted-in launcher, usage answered from the
       #   projection and a boot only for a line that runs a verb; for any other, the boot and
       #   dispatch every launcher has always had, byte for byte
-      def entry(name, boot, shown, opted)
-        opted ? described_entry(name, boot, shown) : plain_entry(name, boot, shown)
+      def entry(name, boot, shown, opted, quiet: false)
+        opted ? described_entry(name, boot, shown, quiet: quiet) : plain_entry(name, boot, shown)
       end
 
       # @api private
       # @return [String] the opted-in launcher's middle
-      def described_entry(name, boot, shown)
+      def described_entry(name, boot, shown, quiet: false)
+        started = "Hecks.boot_described(described, install_doors: false)"
+        started = "Hecks::Doors::LauncherOptions.quietly(hold: MEMORY_VERBS.include?(ARGV.first)) { #{started} }" if quiet
         <<~RUBY.chomp
           # Usage is answered from the projected chapter alone: no adapter is bound and no
           # database is opened. Only a line that runs a verb boots the domain,
@@ -227,7 +231,7 @@ module Hecks
           )
           unless text
             runtime = begin
-              Hecks.boot_described(described, install_doors: false)
+              #{started}
             rescue StandardError => e
               abort "cannot open #{name}: \#{e.message.lines.first.strip}"
             end
@@ -264,6 +268,31 @@ module Hecks
         raise ArgumentError, "#{what} #{value.to_s.inspect} is not a plain word or path"
       end
 
+      # @api private
+      # @param ending [String] the launcher's closing lines
+      # @return [String] the same lines, except that a memory verb that ended well prints nothing: a
+      #   person is at it, so the settled record is noise after the session
+      def quiet_ending(ending)
+        ending.sub("status.zero? ? puts(text)",
+                   "exit 0 if status.zero? && MEMORY_VERBS.include?(ARGV.first)\nstatus.zero? ? puts(text)")
+      end
+
+      # @api private
+      # @return [String] the lines that default the listed verbs to Memory, or nothing
+      def memory_default(verbs)
+        return "" if verbs.empty?
+
+        verbs.each { |verb| plain!("memory verb", verb, VERB) }
+
+        <<~RUBY
+
+          # These verbs keep nothing worth a database, so they run on Memory unless told otherwise, and
+          # print nothing when they end well.
+          MEMORY_VERBS = %w[#{verbs.join(' ')}].freeze
+          ENV["HECKS_ENVIRONMENT"] ||= "memory" if MEMORY_VERBS.include?(ARGV.first)
+        RUBY
+      end
+
       # @api private
       # @return [String] the lines that hand the legacy verbs to `Hecks::CLI`, or nothing
       def legacy_handoff(legacy)

data/lib/hecks/cli/seed_semantics_corpus.rb

@@ -7,9 +7,12 @@ require_relative "../fuzzing"
 module Hecks
   module CLI
     # The command behind `hecks seed_semantics_corpus`: seeds (or deliberately re-seeds) the
-    # `expect` block of semantics-corpus fixtures from the Ruby runtime. Review the result
+    # `expect` block of corpus fixtures from the Ruby runtime. Review the result
     # against `docs/semantics/bluebook-semantics.md` before committing.
     #
+    # Seeds `spec/corpus/semantics/` and the conformance corpus ({FULL_SCRIPTS} plus
+    # `spec/corpus/rust_conformance/`, whose `expect` also freezes more).
+    #
     #   hecks seed_semantics_corpus                                # fill fixtures missing an expect
     #   SEED=refusal_kind_lifecycle hecks seed_semantics_corpus    # re-seed one, deliberately
     #
@@ -18,6 +21,15 @@ module Hecks
     module SeedSemanticsCorpus
       module_function
 
+      # Full corpus scripts held to the conformance bar, keyed by file, valued by domain.
+      FULL_SCRIPTS = {
+        "spec/corpus/banking.json" => "examples/banking",
+        "spec/corpus/chess.json"   => "examples/chess"
+      }.freeze
+
+      # The `expect` keys a conformance fixture freezes beyond the semantics three.
+      CONFORMANCE_KEYS = %w[queries sagas dry_runs reactions].freeze
+
       # Seeds the fixtures that need it and reports which.
       #
       # @param root [String] the checkout whose `spec/corpus/semantics/` is seeded
@@ -26,12 +38,13 @@ module Hecks
       # @return [Integer] the exit status, always 0
       def call(root:, env: ENV, out: $stdout)
         only = env.fetch("SEED", nil)
-        seeded = Dir.glob(File.join(root, "spec/corpus/semantics", "*.json")).filter_map do |path|
+        seeded = corpus_paths(root).filter_map do |path, domain, full|
           fixture = JSON.parse(File.read(path))
           name = File.basename(path, ".json")
           next if only ? only != name : fixture.key?("expect")
 
-          fixture["expect"] = expectation_for(root, fixture)
+          fixture["domain"] ||= domain if domain
+          fixture["expect"] = expectation_for(root, fixture, full: full)
           File.write(path, "#{JSON.pretty_generate(fixture)}\n")
           name
         end
@@ -39,19 +52,35 @@ module Hecks
         0
       end
 
+      # @param root [String] the checkout
+      # @return [Array<Array>] `[path, domain_to_add_or_nil, full_expect?]` for every seedable file
+      def corpus_paths(root)
+        semantics = Dir.glob(File.join(root, "spec/corpus/semantics", "*.json")).map { |p| [p, nil, false] }
+        conformance = Dir.glob(File.join(root, "spec/corpus/rust_conformance", "*.json")).map { |p| [p, nil, true] }
+        scripts = FULL_SCRIPTS.map { |file, domain| [File.join(root, file), domain, true] }
+        semantics + conformance + scripts
+      end
+
       # Replays the fixture's script against the Ruby runtime. Each refusal's `"kind"` is reduced
       # to its class name; `occurred_at` is stripped from events.
       #
       # @param root [String] the checkout the fixture's domain path is relative to
       # @param fixture [Hash] the parsed fixture: `domain` and `steps`
-      # @return [Hash{String => Array}] its `"expect"` block: refusals, instances, events
-      def expectation_for(root, fixture)
+      # @param full [Boolean] also freeze queries, sagas, dry runs, reactions (conformance)
+      # @return [Hash{String => Array}] its `"expect"` block: refusals, instances, events, and
+      #   with `full` the {CONFORMANCE_KEYS}
+      def expectation_for(root, fixture, full: false)
         result = Hecks::Fuzzing::Replay.call(File.join(root, fixture["domain"]), fixture["steps"])
-        {
+        expect = {
           "refusals"  => JSON.parse(JSON.generate(result[:refusals])).each { |r| r["kind"] = r["kind"]&.split("::")&.last },
           "instances" => JSON.parse(JSON.generate(result[:instances])),
           "events"    => JSON.parse(JSON.generate(result[:events])).each { |e| e.delete("occurred_at") }
         }
+        return expect unless full
+
+        # instances_at is Replay's per-query snapshot for the property harness, not an outcome.
+        expect["queries"] = JSON.parse(JSON.generate(result[:queries].map { |q| q.except(:instances_at) }))
+        expect.merge!(CONFORMANCE_KEYS.drop(1).to_h { |k| [k, JSON.parse(JSON.generate(result[k.to_sym]))] })
       end
 
       # @param out [IO] where the report goes

data/lib/hecks/doors/launcher_options.rb

@@ -1,3 +1,4 @@
+require "stringio"
 require_relative "../ports/identity_generation"
 require_relative "../runtime/errors"
 require_relative "cli_door"
@@ -46,6 +47,23 @@ module Hecks
         { program: program, names: settings && settings[:names], mint_run_keys: settings && settings[:run_keys] }
       end
 
+      # Runs the block with standard error held back, so the wiring notes hecks prints about its own
+      # chapters (a Memory journal loses sagas on restart) do not open a console session. They are
+      # for an operator running a stored journal. A raised error still surfaces, unchanged.
+      #
+      # @param hold [Boolean] whether to hold standard error back; false runs the block as it is
+      # @yield the boot
+      # @return [Object] the block's value
+      def quietly(hold: true)
+        return yield unless hold
+
+        shown = $stderr
+        $stderr = StringIO.new
+        yield
+      ensure
+        $stderr = shown if hold
+      end
+
       # Takes `--wait` out of a verb's words, unless the verb declares a `wait` argument of its own.
       #
       # `--wait=false` (or `no`, `0`, `off`) is a `--wait` that was switched off; a bare `--wait`

data/lib/hecks/gate/stages.yml

@@ -45,6 +45,10 @@ pre_push:
       title: codegen drift, the committed rust/src/generated/ must match a fresh regeneration
       run: [bundle, exec, exe/hecks, regenerate_corpus, --check, --wait]
       blocked: regenerating hits a diff, so the committed Rust is stale; run `hecks regenerate_corpus --confirm` and commit the result.
+    - id: comment_style
+      title: comment style, every comment under lib/hecks against docs/COMMENT_STYLE_GUIDE.md
+      run: [bundle, exec, exe/hecks, check_comments, paths=lib/hecks, --wait]
+      blocked: a comment breaks the style guide, such as a line past 100 characters; `hecks fix_comments` rewrites the mechanical ones, and the rest are shortened by hand. CI runs this same check.
     - id: comment_blocks
       title: comment blocks, no run of comment lines past ADR 0075's cap
       run: [bundle, exec, exe/hecks, check_comments, "paths=lib,spec,examples", only=long_block, --wait]

data/lib/hecks/hecks/hecks.world

@@ -26,8 +26,10 @@
 # `failure_states` are the lifecycle states `--wait` reports as exit 1 (every failure state the
 # chapter's lifecycles declare), `names` gives a command the launcher name clients type,
 # `executable` is where `hecks project_cli` writes this chapter's launcher (the gem's
-# `exe/hecks`), `streams` lists the questions `--stream` may tail (`Follow`), and `legacy` names
-# the verbs that launcher hands to `Hecks::CLI` in the positional forms ADR 0066 shipped.
+# `exe/hecks`), `streams` lists the questions `--stream` may tail (`Follow`), `memory_verbs` names
+# the verbs that launcher runs on the Memory environment unless `HECKS_ENVIRONMENT` is set (so
+# `hecks console` needs no database), and `legacy` names the verbs it hands to `Hecks::CLI` in the
+# positional forms ADR 0066 shipped.
 Hecks.world "Hecks" do
   realm "Hecks"
   default_adapter "PostgresEra"
@@ -38,6 +40,7 @@ Hecks.world "Hecks" do
                        names: { "mcp" => "serve_mcp", "console" => "open_console" },
                        streams: %w[Follow],
                        executable: "exe/hecks",
+                       memory_verbs: %w[console],
                        legacy: %w[run docs narrate ir stores model_check smoke_test
                                   project_diagrams project_cli mcp]
 end

data/lib/hecks/ports/persistence/plugins/era/postgres_era.rb

@@ -123,7 +123,8 @@ module Hecks
         raise unless defined?(PG::Error) && e.is_a?(PG::Error)
 
         raise Runtime::WiringError,
-              "cannot bind PostgresEra at #{declared} for #{name}: #{e.message.strip}"
+              "cannot bind PostgresEra at #{declared} for #{name}: #{e.message.strip} " \
+              "-- to run without a database, set HECKS_ENVIRONMENT=memory (a domain needs an environments/memory overlay)"
       end
 
       # Joins the process's shared connection for the declared database and schema, so every

data/lib/hecks/projector/cli_projector.rb

@@ -206,6 +206,7 @@ module Hecks
 
         { verb: fqn(bluebook, aggregate, command, entity), kind: :command,
           summary: command.goal, role: command.role, role_gated: !command.role.to_s.empty?,
+          group: aggregate.hecks_name, internal: command.role.to_s == "System",
           creates: command.creates?,
           receiver: receiver, legacy_receiver: (receiver == :aggregate ? :id : nil),
           legacy_arguments: legacy_arguments,
@@ -230,7 +231,7 @@ module Hecks
                 else
                   "#{port.name} telling #{aggregate.hecks_name}"
                 end,
-          role_gated: false,
+          role_gated: false, group: aggregate.hecks_name, internal: true,
           summary: port_summary(port, operation), arguments: arguments }
       end
 
@@ -257,13 +258,30 @@ module Hecks
           summary: model.description, arguments: arguments }
       end
 
+      # A question that only reads the aggregate's own records back: it returns no document and
+      # filters on nothing but the record's identity ("how one request ended") or its lifecycle
+      # status ("every request that was refused"). Each journaled run has such a pair, which a
+      # person reads through `hecks <verb> --wait` rather than asking for by name, so the help
+      # sets them apart with the bookkeeping verbs. A query that returns a document, or filters
+      # on anything else, is a real question. Only an aggregate that journals its own runs (it has
+      # system-role commands, the ones `internal` verbs are made of) has such a pair: a release's
+      # "every version that was shipped" is a question worth asking by name.
+      def bookkeeping_query?(aggregate, query)
+        return false if query.returns || query.wheres.empty?
+        return false unless aggregate.commands.any? { |command| command.role.to_s == "System" }
+
+        own = Array(aggregate.identified_by).map(&:to_s) + [aggregate.lifecycle&.field.to_s]
+        query.wheres.all? { |clause| own.include?(clause.field.to_s) }
+      end
+
       def query_spec(bluebook, aggregate, entity, query)
         arguments = Array(query.to_h[:attributes]).flat_map do |declared|
           attribute = query.attributes.find { |a| a.name.to_s == declared[:name].to_s }
           attribute ? options_for(attribute, entity || aggregate, aggregate) : []
         end
 
-        { verb: fqn(bluebook, aggregate, query, entity), kind: :query,
+        { verb: fqn(bluebook, aggregate, query, entity), kind: :query, group: aggregate.hecks_name,
+          internal: entity.nil? && bookkeeping_query?(aggregate, query),
           summary: query.description, arguments: arguments, returns: query.returns }
       end
 
@@ -373,16 +391,57 @@ module Hecks
                "  #{program} ask <question> [name=value …]  read something", ""]
 
         out << "verbs:"
-        verbs.each_value { |spec| out << "  #{spec[:short].ljust(width)}  #{spec[:summary]}" }
+        out.concat(listing(verbs, width) { |spec| spec[:summary] })
         out << ""
         out << "questions (nothing here changes anything):"
-        questions.each_value { |spec| out << "  #{spec[:short].ljust(width)}  #{first_sentence(spec[:summary])}" }
+        out.concat(listing(questions, width) { |spec| first_sentence(spec[:summary]) })
         out << ""
         out << "  #{program} <verb> --help       what one verb wants, and every way it refuses"
         out << "  a verb can always be spelled in full — #{example_qualified(verbs)}"
         out.join("\n")
       end
 
+      # The verb or question lines of the help. A domain with more than one aggregate is listed
+      # under a heading per aggregate, so related verbs sit together; 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)
+        shown, internal = specs.values.partition { |spec| !spec[:internal] }
+        groups = shown.group_by { |spec| spec[:group] }
+        lines = []
+        if groups.length > 1
+          groups.each do |group, members|
+            lines << "  #{heading(group)}" if group
+            members.each { |spec| lines << "    #{spec[:short].ljust(width)}  #{yield(spec)}" }
+          end
+        else
+          shown.each { |spec| lines << "  #{spec[:short].ljust(width)}  #{yield(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").
+      def heading(group)
+        words = Naming.snake(group.sub(/Run\z/, "")).tr("_", " ")
+        "#{words.capitalize}:"
+      end
+
+      # The internal verbs as bare names, wrapped, under one line saying what they are.
+      def internal_lines(specs)
+        lines = ["  internal — what a run records about itself, named here only (`--help` still works):"]
+        line = "   "
+        specs.map { |spec| spec[:short] }.each do |name|
+          if line.length + name.length + 1 > 98
+            lines << line
+            line = "   "
+          end
+          line += " #{name}"
+        end
+        lines << line
+      end
+
       # One verb whose full spelling differs from its short one, or `""` when none does.
       def example_qualified(verbs)
         name, spec = verbs.find { |key, value| key != value[:short] } || verbs.first

data/lib/hecks/runtime/command_interpreter.rb

@@ -243,6 +243,8 @@ module Hecks
         target_args = ctx.args.merge(
           delegation.source.to_h { |target_key, source_key| [target_key.to_sym, ctx.args[source_key]] }
         )
+        # The target is dispatched as if called directly, so its needs and defaults are filled too.
+        target_args = enrich_arguments(target_command, target_args)
 
         refuse_unknown_arguments(ctx.domain, ctx.aggregate, target_command, target_args,
                                  extra_identity_heads: entity.identity_heads)

data/lib/hecks/runtime/interpreting.rb

@@ -29,12 +29,33 @@ module Hecks
       # @return [Hash{Symbol => Object}] `args`, with each missing needed fact answered
       # @raise [Runtime::WiringError] when the port that answers a fact is not bound exactly once
       def enrich_arguments(command, args)
+        fill_defaults(command, fill_needs(command, args))
+      end
+
+      # Answers each fact the command `needs` that the caller left out.
+      def fill_needs(command, args)
         missing = command.needs.reject { |fact| args.key?(fact) || args.key?(fact.to_s) }
         return args if missing.empty?
 
         args.merge(missing.to_h { |fact| [fact, need_value(command, fact)] })
       end
 
+      # Gives each argument the caller left out the default its attribute declares
+      # (`attribute :runs, Count, default: 30`), so a declared default holds on every way in and
+      # not only where a door spells it out. An argument the caller passed is kept, whatever it is.
+      #
+      # @param command [Class] the command being dispatched
+      # @param args [Hash{Symbol => Object}] the arguments the caller passed
+      # @return [Hash{Symbol => Object}] `args`, with each absent defaulted argument filled
+      def fill_defaults(command, args)
+        absent = command.attributes.reject do |attribute|
+          attribute.default.nil? || args.key?(attribute.name.to_sym) || args.key?(attribute.name.to_s)
+        end
+        return args if absent.empty?
+
+        args.merge(absent.to_h { |attribute| [attribute.name.to_sym, attribute.default] })
+      end
+
       # The answer to one fact, in the shape the command's argument of that name takes: a bare
       # Integer for an Integer attribute, else the one-field value object the language declares
       # for an instant.

data/lib/hecks/runtime/invocation.rb

@@ -207,12 +207,14 @@ module Hecks
                                            declared: declared)
         end
 
-        # A fact the command `needs` is not absent: the interpreter answers it before any refusal
-        # reads the arguments.
+        # A fact the command `needs`, and an argument its attribute gives a default, are not absent:
+        # the interpreter fills them before any refusal reads the arguments.
         def refuse_absent_facts!(declaring, offered, declared)
           needed = declaring.respond_to?(:needs) ? declaring.needs.map(&:to_sym) : []
+          defaulted = declaring.attributes.select { |attribute| attribute.respond_to?(:default) && !attribute.default.nil? }
+                               .map { |attribute| attribute.name.to_sym }
           absent = declaring.attributes.reject(&:optional?).map { |attribute| attribute.name.to_sym } -
-                   offered.keys - needed
+                   offered.keys - needed - defaulted
           return if absent.empty?
 
           raise AbsentArgument,

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.0.4".freeze
+  VERSION = "3.0.5".freeze
 end

data/rust/host/HECKS_RELEASE

@@ -1 +1 @@
-3.0.4
+3.0.5

data/rust/host/src/web/newsletter/template.rs

@@ -0,0 +1,69 @@
+// The optional branded confirmation email: an HTML template an operator
+// hosts, fetched at send time. Hecks ships no brand; with no template (or
+// any trouble with one) the caller keeps the plain-text body.
+use super::super::newsletter_send::personalize;
+use std::time::Duration;
+
+pub(super) const CONFIRM_TOKEN: &str = "{{CONFIRM_URL}}";
+const FETCH_TIMEOUT: Duration = Duration::from_secs(5);
+pub(super) const MAX_TEMPLATE_BYTES: usize = 256 * 1024;
+
+// Escapes a URL for an HTML attribute or text position.
+fn escape_html(value: &str) -> String {
+    value.replace('&', "&amp;").replace('<', "&lt;").replace('>', "&gt;").replace('"', "&quot;").replace('\'', "&#39;")
+}
+
+// Fills the placeholders with HTML-escaped URLs. `Err` names why the
+// template is unusable: without {{CONFIRM_URL}} the email would carry no
+// link. {{UNSUBSCRIBE_URL}} is optional. The result starts at its first
+// non-blank character so the mailer sends it as HTML.
+pub(super) fn fill_template(template: &str, confirm_url: &str, unsubscribe_url: &str) -> Result<String, &'static str> {
+    if !template.contains(CONFIRM_TOKEN) {
+        return Err("the template has no {{CONFIRM_URL}} placeholder");
+    }
+    let filled = template.replace(CONFIRM_TOKEN, &escape_html(confirm_url));
+    Ok(personalize(&filled, &escape_html(unsubscribe_url)).trim_start().to_string())
+}
+
+// Reads a response body, stopping as soon as it passes the cap.
+async fn read_capped(mut response: reqwest::Response) -> Result<String, String> {
+    let mut bytes: Vec<u8> = Vec::new();
+    while let Some(chunk) = response.chunk().await.map_err(|e| e.to_string())? {
+        bytes.extend_from_slice(&chunk);
+        if bytes.len() > MAX_TEMPLATE_BYTES {
+            return Err(format!("the template is larger than {MAX_TEMPLATE_BYTES} bytes"));
+        }
+    }
+    String::from_utf8(bytes).map_err(|_| "the template is not UTF-8".to_string())
+}
+
+// GETs the template (5 second timeout, size capped); a non-2xx answer or
+// any transport trouble is an `Err` with the reason.
+async fn fetch_template(url: &str) -> Result<String, String> {
+    let http = reqwest::Client::builder().timeout(FETCH_TIMEOUT).build().map_err(|e| e.to_string())?;
+    let response = http.get(url).send().await.map_err(|e| e.to_string())?;
+    if !response.status().is_success() {
+        return Err(format!("the template answered {}", response.status()));
+    }
+    read_capped(response).await
+}
+
+// The HTML body when NEWSLETTER_CONFIRMATION_TEMPLATE_URL names a usable
+// template; None (after logging why) when the caller should send plain text.
+pub(super) async fn branded_body(confirm_url: &str, unsubscribe_url: &str) -> Option<String> {
+    let url = std::env::var("NEWSLETTER_CONFIRMATION_TEMPLATE_URL").ok().filter(|u| !u.trim().is_empty())?;
+    let template = match fetch_template(url.trim()).await {
+        Ok(t) => t,
+        Err(e) => {
+            eprintln!("newsletter: the confirmation template could not be fetched ({e}), so the plain-text confirmation was sent");
+            return None;
+        }
+    };
+    match fill_template(&template, confirm_url, unsubscribe_url) {
+        Ok(body) => Some(body),
+        Err(e) => {
+            eprintln!("newsletter: the confirmation template was rejected ({e}), so the plain-text confirmation was sent");
+            None
+        }
+    }
+}

data/rust/host/src/web/newsletter/tests.rs

@@ -102,3 +102,46 @@ fn a_confirm_token_is_not_an_unsubscribe_token_and_the_reverse() {
     assert!(!unsubscribe_token_matches("s3cret-value", &confirm, "a@example.com"));
     assert!(!confirm_token_matches("s3cret-value", &unsubscribe, "a@example.com"));
 }
+
+use template::fill_template;
+
+const CONFIRM: &str = "https://example.com/newsletter-confirmed.html?email=a%40b.c&token=t";
+const UNSUBSCRIBE: &str = "https://example.com/newsletter-unsubscribed.html?email=a%40b.c&token=u";
+
+#[test]
+fn a_template_gets_the_confirm_link_in_place_of_its_placeholder() {
+    let body = fill_template("<p><a href=\"{{CONFIRM_URL}}\">Confirm</a></p>", CONFIRM, UNSUBSCRIBE).unwrap();
+    assert_eq!(body, "<p><a href=\"https://example.com/newsletter-confirmed.html?email=a%40b.c&amp;token=t\">Confirm</a></p>");
+}
+
+#[test]
+fn a_template_without_the_confirm_placeholder_is_rejected() {
+    assert!(fill_template("<p>{{UNSUBSCRIBE_URL}}</p>", CONFIRM, UNSUBSCRIBE).is_err());
+    assert!(fill_template("", CONFIRM, UNSUBSCRIBE).is_err());
+}
+
+#[test]
+fn the_unsubscribe_placeholder_is_optional_and_replaced_wherever_present() {
+    assert!(fill_template("<a href=\"{{CONFIRM_URL}}\">x</a>", CONFIRM, UNSUBSCRIBE).is_ok());
+    let body = fill_template("<a href=\"{{CONFIRM_URL}}\">x</a>{{UNSUBSCRIBE_URL}}|{{UNSUBSCRIBE_URL}}", CONFIRM, UNSUBSCRIBE).unwrap();
+    assert!(!body.contains("{{"));
+    assert_eq!(body.matches("newsletter-unsubscribed.html").count(), 2);
+}
+
+#[test]
+fn ampersands_and_quotes_in_a_url_are_escaped_inside_the_html() {
+    let body = fill_template("<a href=\"{{CONFIRM_URL}}\">x</a>", "https://e.com/?a=1&b=\"2\"<>'", UNSUBSCRIBE).unwrap();
+    assert_eq!(body, "<a href=\"https://e.com/?a=1&amp;b=&quot;2&quot;&lt;&gt;&#39;\">x</a>");
+}
+
+#[test]
+fn a_filled_template_starts_at_its_first_tag_so_the_mailer_sends_html() {
+    let body = fill_template("\n  <p>{{CONFIRM_URL}}</p>", CONFIRM, UNSUBSCRIBE).unwrap();
+    assert!(body.starts_with('<'));
+}
+
+#[test]
+fn without_a_template_the_plain_text_confirmation_is_unchanged() {
+    let body = confirmation_body(CONFIRM);
+    assert_eq!(body, format!("Please confirm your newsletter subscription by opening this link:\n\n{CONFIRM}\n\nIf you didn't ask for this, you can ignore this email and nothing will be sent to you.\n"));
+}

data/rust/host/src/web/newsletter.rs

@@ -14,6 +14,7 @@ use tokio::sync::Mutex;
 use tokio_postgres::Client;
 
 mod cooldown;
+mod template;
 #[cfg(test)]
 mod tests;
 
@@ -194,8 +195,12 @@ pub(super) async fn send_confirmation(email: &str) {
     let site = site_url();
     let link = confirm_url(&site, email, &confirm_token(&secret, email));
     let unsubscribe = unsubscribe_url(&site, email, &unsubscribe_token(&secret, email));
+    let body = match template::branded_body(&link, &unsubscribe).await {
+        Some(html) => html,
+        None => confirmation_body(&link),
+    };
     let delivery = mailer
-        .deliver(&Email { to: email, subject: "Confirm your newsletter subscription", body: &confirmation_body(&link), unsubscribe_url: Some(&unsubscribe) })
+        .deliver(&Email { to: email, subject: "Confirm your newsletter subscription", body: &body, unsubscribe_url: Some(&unsubscribe) })
         .await;
     if !delivery.ok {
         eprintln!("newsletter: the confirmation email was not delivered: {}", delivery.reason.unwrap_or_default());

data/rust/host/src/web/newsletter_send.rs

@@ -132,7 +132,7 @@ pub(super) fn unsubscribe_url(site_url: &str, email: &str, token: &str) -> Strin
     url.to_string()
 }
 
-fn personalize(body: &str, unsubscribe_url: &str) -> String {
+pub(super) fn personalize(body: &str, unsubscribe_url: &str) -> String {
     body.replace(UNSUBSCRIBE_TOKEN, unsubscribe_url)
 }
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hecks
 version: !ruby/object:Gem::Version
-  version: 3.0.4
+  version: 3.0.5
 platform: ruby
 authors:
 - Chris Young
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-02 00:00:00.000000000 Z
+date: 2026-10-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: prism
@@ -858,6 +858,7 @@ files:
 - rust/host/src/web.rs
 - rust/host/src/web/newsletter.rs
 - rust/host/src/web/newsletter/cooldown.rs
+- rust/host/src/web/newsletter/template.rs
 - rust/host/src/web/newsletter/tests.rs
 - rust/host/src/web/newsletter_send.rs
 - rust/host/src/web/registrations.rs