hecks 6.0.0 → 7.0.0

data/lib/hecks/runtime/dry_run_plan.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Runtime
+    # What an in-memory dispatch would have written and announced, collected while the dispatch
+    # runs. The command interpreter reports each save and each emitted event here when it runs
+    # in dry mode, so every command gets a plan from the same seam with no per-command code.
+    module DryRunPlan
+      KEY = :hecks_dry_run_plan
+
+      module_function
+
+      # Runs the block and returns the lines it would have produced.
+      #
+      # @yield the in-memory dispatch
+      # @return [Array<String>] one `would …` line per write or event, in order
+      def collect
+        previous = Thread.current[KEY]
+        Thread.current[KEY] = []
+        yield
+        Thread.current[KEY]
+      ensure
+        Thread.current[KEY] = previous
+      end
+
+      # Records one write the dispatch would make.
+      #
+      # @param aggregate [Bluebook::Aggregate] the aggregate the record belongs to
+      # @param instance [Runtime::Instance] the record the dispatch would write
+      # @return [void]
+      def write(aggregate, instance)
+        record("would write #{aggregate.hecks_name} #{instance.id}")
+      end
+
+      # Records one event the dispatch would announce.
+      #
+      # @param name [String] the event's name
+      # @return [void]
+      def emit(name)
+        record("would emit #{name}")
+      end
+
+      # Records each event a command announces.
+      #
+      # @param command [Bluebook::Command] the command the dispatch runs
+      # @return [void]
+      def emits(command)
+        command.emits.each { |name| emit(name) }
+      end
+
+      # Appends a line when a plan is being collected; otherwise does nothing.
+      #
+      # @param line [String]
+      # @return [void]
+      def record(line)
+        Thread.current[KEY]&.push(line)
+      end
+    end
+  end
+end

data/lib/hecks/runtime/entity_element/location.rb

@@ -26,7 +26,6 @@ module Hecks
         # Walks `chain` one hop at a time and returns the located element (or `instance`
         # itself when `chain` is empty). `route`, when given, offers each hop's identity
         # before falling back to `args`.
-        # rubocop:disable-next Metrics/ParameterLists -- the positional entry point EntityInterpreter and delegation call
         def locate_chain(root_aggregate, chain, instance, args, command_name, route = nil)
           container = instance
           owner     = root_aggregate

data/lib/hecks/runtime/entity_element/mutations.rb

@@ -37,7 +37,6 @@ module Hecks
         # Applies one declared mutation to an entity element, in place. `pre` is the
         # element as it stood before this command: every read goes through it, every
         # write lands on `element`.
-        # rubocop:disable-next Metrics/ParameterLists -- the positional signature callers (and specs) wrap
         def apply_to_element(rules, aggregate, entity, element, mutation, args, pre = element)
           handler = OP_HANDLERS.fetch(mutation.op) do
             # Backstop: an unhandled op must refuse, not silently apply nothing.

data/lib/hecks/runtime/entity_interpreter/locating.rb

@@ -19,7 +19,12 @@ module Hecks
           ctx.instance = step(:hydrate_parent) { parent_record(ctx) }
         end
 
+        # A validation records `hydrate_parent`'s refusal and goes on within the stage, so the
+        # parent may be missing here: then there is nothing to locate in, and the one refusal
+        # already recorded is the answer a dispatch raises.
         def step_locate_element(ctx)
+          return unless ctx.instance
+
           ctx.element = step(:locate_element) do
             EntityElement.locate_chain(ctx.aggregate, ctx.chain, ctx.instance, ctx.args, ctx.command_name, ctx.route)
           end

data/lib/hecks/runtime/entity_interpreter.rb

@@ -48,7 +48,6 @@ module Hecks
       # `element`/`view` are the entity piece itself, pre- and
       # post-mutation. `:chain` intentionally shadows Enumerable#chain —
       # every read is the struct field, never enumerable-combining.
-      # rubocop:disable-next Lint/StructNewOverride
       Context = Struct.new(:domain, :aggregate, :entity, :entity_name, :command, :command_name,
                            :args, :repository, :instance, :chain, :element, :view, :transition,
                            :old_element, :result, :route, :plan, :persistence_outcome, :dry_run, :outbox_rows,

data/lib/hecks/runtime/errors.rb

@@ -88,5 +88,31 @@ module Hecks
     # Names come from the language; resolving them here fails at load if one is undefined.
     # Each is a `Hecks::Refused`, and nothing else is, so rescuing either catches the same set.
     DOMAIN_REFUSALS = Hecks::Vocabulary.fetch("DomainRefusal").map { |name| const_get(name) }.freeze
+
+    # The errors that mean the code is wrong, not that the outside world said no: a name that
+    # does not resolve (`NameError`, and `NoMethodError` under it), a value of the wrong class
+    # (`TypeError`), a write to a frozen value (`FrozenError`), and code that would not load
+    # (`ScriptError`: `LoadError`, `NotImplementedError`, `SyntaxError`). An ask that meets one
+    # raises it instead of announcing its `refuses` event, so the defect is seen where it happens.
+    #
+    # `ArgumentError` is left out on purpose: adapters raise its subclasses to refuse input they
+    # were handed (`TenantProvisioner::Refused`, `Composer::Workspace::OutsideWorkspace`), and
+    # parsing outside data raises it (`Integer("x")`, `Date::Error`), so it is the world saying no
+    # as often as it is a wrong call.
+    PROGRAMMING_ERRORS = [NameError, TypeError, FrozenError, ScriptError].freeze
+
+    # @param error [Exception] the error an adapter raised
+    # @return [Boolean] whether `error` is a defect in the code rather than a refusal
+    def self.programming_error?(error) = PROGRAMMING_ERRORS.any? { |kind| error.is_a?(kind) }
+
+    # The refusal text of a failure an ask records: its class and message. An error raised with no
+    # message still names its class, so a refusal never arrives empty.
+    #
+    # @param error [Exception] the error an adapter raised
+    # @return [String] `"Class: message"`, never blank
+    def self.failure_reason(error)
+      message = error.message.to_s.strip
+      "#{error.class}: #{message.empty? ? "raised with no message" : message}"
+    end
   end
 end

data/lib/hecks/runtime/instance.rb

@@ -19,7 +19,6 @@ module Hecks
       # `hydrate_with:` replaces the default hydration with a callable that takes the given
       # state and answers the hydrated one (defaults filled), for an adapter that can reuse
       # work across saves.
-      # rubocop:disable-next Metrics/ParameterLists -- the public keyword constructor every caller spells out
       def initialize(aggregate:, id:, state: nil, args: nil, hydrate: true, hydrate_with: nil)
         @aggregate = aggregate
         @id        = id

data/lib/hecks/runtime/invocation_builder.rb

@@ -21,7 +21,6 @@ module Hecks
       # :entity, :port). Each checks its own parts in a fixed order, because
       # a malformed call's refusal depends on that order; `declaring` is
       # called exactly once, at that shape's point in the order below.
-      # rubocop:disable-next Metrics/ParameterLists -- the public keyword entry point every dispatch calls
       def from_call(verb, to:, with:, flat:, receiver: :aggregate, entity_depth: 0, aggregate: nil, &declaring)
         call = Call.new(verb, to, with, flat, entity_depth, aggregate, declaring)
         case receiver

data/lib/hecks/runtime/outbox/consumer_runner.rb

@@ -15,7 +15,7 @@ module Hecks
           kind, fqn = row.consumer.split(":", 2)
           home, name = fqn.split("::", 2)
           case kind
-          when "policy" then run_policy(row, event, fqn, home, name)
+          when "policy" then refusal_reason(run_policy(row, event, fqn, home, name))
           when "saga" then run_saga(row, event, fqn, home, name)
           else
             raise WiringError, "outbox row #{row.delivery_id} has an unknown consumer kind #{kind.inspect}"
@@ -28,11 +28,19 @@ module Hecks
           @policies.react(event, row.domain, only: [policy, home], event_uid: row.event_uid)
         end
 
+        # The reason the domain refused a policy's reaction, nil when none was refused. A defect
+        # is not a refusal: it is warned where it happens and the row settles as before.
+        def refusal_reason(records)
+          refused = Array(records).find { |record| record[:delivered] == false && !record[:defect] }
+          refused && (refused[:reason].to_s.empty? ? "refused (no reason given)" : refused[:reason].to_s)
+        end
+
         def run_saga(row, event, fqn, home, name)
           process_manager = @registry.bluebook(home)&.process_managers&.find { |candidate| candidate.name == name } ||
                             raise(WiringError,
                                   "outbox row #{row.delivery_id} names process_manager #{fqn}, which no bluebook declares")
           @sagas.advance(event, row.domain, only: process_manager)
+          nil
         end
       end
     end

data/lib/hecks/runtime/outbox/relay.rb

@@ -31,6 +31,26 @@ module Hecks
 
         def attached? = !@policies.nil?
 
+        # Runs one policy's reaction to `event`, as a row's delivery runs it: its outcome is
+        # recorded on the registry's reaction log, a refusal included, and nothing is raised.
+        #
+        # @param event [Runtime::Event] the event the policy reacts to
+        # @param policy [Bluebook::Policy] the policy to run
+        # @param home [String] the bluebook the policy is declared in
+        # @param domain [String] the domain the event came from
+        # @param event_uid [String] the identity the reaction log records for the event
+        # @return [void]
+        def react_policy(event, policy:, home:, domain:, event_uid:)
+          @policies.react(event, domain, only: [policy, home], event_uid: event_uid)
+        end
+
+        # Answers the policies `event` triggers in `domain`, as `[policy, home]` pairs.
+        #
+        # @param event [Runtime::Event] the event to react to
+        # @param domain [String] the domain the event came from
+        # @return [Array(Bluebook::Policy, String)]
+        def policies_for(event, domain) = @policies.policies_for(event, domain)
+
         # Forgets every delivery the relay recorded, as a fresh boot starts with none.
         #
         # @return [void]
@@ -82,11 +102,12 @@ module Hecks
         private
 
         def settle_delivery(row, repository)
-          run_consumer(row)
-          repository.outbox_settle(row.id, status: "delivered")
-          row.status = "delivered"
+          reason = run_consumer(row)
+          row.status = reason ? "refused" : "delivered"
+          repository.outbox_settle(row.id, status: row.status, error: reason)
+          row.error = reason
           true
-        rescue StandardError => e
+        rescue StandardError, ScriptError => e
           settle_failed(row, repository, e)
           false
         end

data/lib/hecks/runtime/outbox/runnable.rb

@@ -48,7 +48,9 @@ module Hecks
         def ask_target(row)
           kind, fqn = row.consumer.split(":", 2)
           home, name = fqn.split("::", 2)
-          policy = kind == "policy" && @registry.bluebook(home)&.policies&.find { |candidate| candidate.name == name }
+          return nil unless kind == "policy"
+
+          policy = @registry.bluebook(home)&.policies&.find { |candidate| candidate.name == name }
           return nil unless policy&.asks?
 
           aggregate_and_port, operation = policy.trigger_command.split(".", 2)

data/lib/hecks/runtime/outbox.rb

@@ -10,8 +10,11 @@ module Hecks
     # A durable outbox (ADR 0053): one row per (event, consumer), written in
     # the same transaction as the aggregate save so a reaction is never lost.
     module Outbox
-      # pending -> claimed -> delivered | failed
-      STATUSES = %w[pending claimed delivered failed].freeze
+      # pending -> claimed -> delivered | failed | refused. A reaction the domain refused (its
+      # trigger was declined, its `with:` read a key the event lacked, the cascade was too deep)
+      # is settled `refused` with the reason in `error`: it ran and said no, which is neither
+      # delivery nor a defect, and a trace reads it back.
+      STATUSES = %w[pending claimed delivered failed refused].freeze
 
       # How long a row stays claimed before it counts as stalled: a claim that old was left by a
       # process that is gone, where a younger one is a reaction running in another process. Ten
@@ -26,6 +29,7 @@ module Hecks
         def claimed?   = status == "claimed"
         def delivered? = status == "delivered"
         def failed?    = status == "failed"
+        def refused?   = status == "refused"
 
         # A claimed row is stalled when its age is unknown or past `STALLED_AFTER`; a younger one is
         # a reaction still running.

data/lib/hecks/runtime/policy_interpreter/fan_out.rb

@@ -7,6 +7,9 @@ module Hecks
       # A `for_each` policy: asks a query which rows the event concerns, and fires the trigger
       # once per row through the {RowSweep} a bulk run shares. Mixed into {PolicyInterpreter}.
       module FanOut
+        # The bare scalar types a `for_each` query may declare as an argument.
+        SCALAR_ARGUMENT_TYPES = %w[String Integer Float].freeze
+
         private
 
         # Runs the `for_each` query against the event payload and fires the trigger once
@@ -45,9 +48,22 @@ module Hecks
         def for_each_query_args(query, event)
           args = event.payload.transform_keys(&:to_sym)
           construct = query && emitting_construct(event)
-          return args unless construct
+          lent_attributes(query, construct, args).each { |attribute| args[attribute.name] = event.id } if construct
+          unwrap_scalar_arguments(query, args)
+        end
+
+        # A bare-scalar query argument takes the one value its single-field value object carries:
+        # the payload hands over the object, but the query declares the scalar, and a query's
+        # argument is shape-checked against its declared type.
+        def unwrap_scalar_arguments(query, args)
+          return args unless query
 
-          lent_attributes(query, construct, args).each { |attribute| args[attribute.name] = event.id }
+          query.attributes.each do |attribute|
+            value = args[attribute.name]
+            next unless value.is_a?(Hash) && value.size == 1 && SCALAR_ARGUMENT_TYPES.include?(attribute.type.to_s)
+
+            args[attribute.name] = value.values.first
+          end
           args
         end
 

data/lib/hecks/runtime/policy_interpreter.rb

@@ -36,23 +36,27 @@ module Hecks
       # @param only [Array(Bluebook::Policy, String), nil] one `[policy, home_domain]`
       #   pair to run exactly (the outbox relay's consumer), instead of scanning every
       #   loaded bluebook for candidates
-      # @param event_uid [String, nil] the outbox uid every consumer of this event shares, when the
-      #   event was rebuilt from an outbox row; otherwise the event object itself is the identity
-      # @return [void]
+      # @param event_uid [String, nil] the outbox uid every consumer of this event shares; the
+      #   reaction identity only when the event has no id
+      # @return [Array<Hash>] the reactions recorded, one per delivery attempted
       def react(event, domain, only: nil, event_uid: nil)
         selected = only ? [only] : policies_for(event, domain)
-        selected.each do |policy, home_domain|
+        selected.flat_map do |policy, home_domain|
           result = deliver(policy, event, home_domain)
-          next if result.nil?
-
-          # A for_each policy answers an array; Array(...) would explode a record Hash.
-          identity = event_uid || event.object_id
-          (result.is_a?(Array) ? result : [result]).each { |record| @registry.log_reaction(record, event: identity) }
+          # A for_each policy answers an array; Array(...) would explode a record Hash. The identity
+          # is the event's own id: a later run recognises the reaction, whichever path ran it.
+          records = result.is_a?(Array) ? result : [result].compact
+          records.each { |record| @registry.log_reaction(record, event: reaction_identity(event, event_uid)) }
         end
       end
 
       private
 
+      # The identity a reaction is logged under: the event's own id, so a later run can recognise
+      # the reaction whichever path delivered the event; the outbox uid or the object when the event
+      # has no id.
+      def reaction_identity(event, event_uid) = event.id || event_uid || event.object_id
+
       # Scans every loaded bluebook, since a policy commonly lives in a different
       # domain than the event it reacts to. Returns [policy, home_domain] pairs: the
       # home domain is the fallback for a bare trigger or for_each route. Order is the
@@ -69,6 +73,10 @@ module Hecks
         end
       end
 
+      # Answers the policies `event` triggers in `domain`, as `[policy, home_domain]` pairs, in
+      # the order a delivery tries them. The event pump reads this, then runs one of them at a time.
+      public :policies_for
+
       # Evaluated against the event payload alone (a policy has no aggregate state).
       # Not rescued here: an EvaluationError must reach `deliver`'s defect rescue, not
       # read as a policy that declined to fire.

data/lib/hecks/runtime/port_operation_interpreter.rb

@@ -86,9 +86,11 @@ module Hecks
         ctx.result = step(:emit) { ctx.operation.outbound? ? ask(ctx) : emit(ctx) }
       end
 
-      # The domain calling out. Any failure, however wide (timeout, bad credential, missing
-      # adapter), becomes the `refuses` event rather than a raise, so a policy can react to it.
-      # The adapter is found by port name across the adapters this boot loaded.
+      # The domain calling out. A failure of the outside world (timeout, bad credential, missing
+      # adapter, the adapter's own refusal) becomes the `refuses` event rather than a raise, so a
+      # policy can react to it. A defect in the code (`Runtime::PROGRAMMING_ERRORS`) is raised:
+      # read as a refusal, it hides its cause behind a domain event. The adapter is found by port
+      # name across the adapters this boot loaded.
       #
       # Unlike an inbound operation, an ask is handed the record's held state: the adapter
       # needs data that lives on the record, and an event payload carries only arguments.
@@ -96,10 +98,21 @@ module Hecks
       def ask(ctx)
         operation = ctx.operation
         announce(ctx, operation.answers, ctx.args.merge(spread(adapter_answer(ctx))))
+      rescue Interrupt
+        refuse_ask(ctx, operation, interrupted(ctx))
       rescue StandardError => e
-        announce(ctx, operation.refuses, ctx.args.merge(refusal: { value: "#{e.class}: #{e.message}" }))
+        raise if Runtime.programming_error?(e)
+
+        refuse_ask(ctx, operation, Runtime.failure_reason(e))
       end
 
+      # Announces an ask's refusal with the text it failed with.
+      def refuse_ask(ctx, operation, text) = announce(ctx, operation.refuses, ctx.args.merge(refusal: { value: text }))
+
+      # The refusal an interrupted ask records: the operation it was in and that it was not
+      # finished, so the run ends faulted with the stage it reached, not open with no record.
+      def interrupted(ctx) = "interrupted during #{ctx.operation_hecks_name}: the run stopped before it finished"
+
       def adapter_answer(ctx)
         payload = held_state(ctx).merge(materialise(ctx.args))
         adapter = adapter_for(ctx)
@@ -117,11 +130,12 @@ module Hecks
       end
 
       # The record, if there is one. A missing record is not an error here: the ask still
-      # goes with only its arguments, since `resolve_references` already checked existence.
+      # goes with only its arguments, since `resolve_references` already checked existence. A
+      # defect in reading the state is raised, as an adapter's is.
       def held_state(ctx)
         ctx.instance ? Value.materialize(ctx.state) : {}
-      rescue StandardError
-        {}
+      rescue StandardError => e
+        Runtime.programming_error?(e) ? raise : {}
       end
 
       # The port this operation belongs to, found through the aggregate rather than

data/lib/hecks/runtime/query_interpreter/arguments.rb

@@ -9,10 +9,11 @@ module Hecks
       module Arguments
         private
 
-        # Coerces with `boundary: false`: a query's declared argument types are not a
-        # runtime shape check. The exception is a nil for a required value-object-typed
-        # argument, which must refuse as a command argument does; passing it through
-        # would run an unfiltered query (a Ruby/Rust divergence).
+        # Coerces a query's arguments exactly as a command's are: a bare scalar of the wrong
+        # type refuses with TypeMismatch before any store is read, and so does a nil for a
+        # required value-object-typed argument, which would otherwise run an unfiltered query
+        # (a Ruby/Rust divergence). The Postgres query builder checks the same shapes
+        # (`Value.check_query_arguments!`), so both engines refuse the same way.
         #
         # It does not use `Value::Coercion#nil_argument`, which builds a null value object
         # from field defaults and only refuses when a field has none. `null_vo_argument!`
@@ -29,7 +30,7 @@ module Hecks
         def coerce_argument(aggregate, attribute, value)
           return null_vo_argument!(aggregate, attribute) if checked_vo?(aggregate, attribute, value)
 
-          Value.for_attribute(aggregate, attribute, value, boundary: false)
+          Value.for_attribute(aggregate, attribute, value)
         end
 
         def checked_vo?(aggregate, attribute, value)

data/lib/hecks/runtime/reaction_invocation.rb

@@ -93,7 +93,6 @@ module Hecks
       # @raise [Runtime::UnknownVerb] if `verb` does not resolve (only when `explicit`)
       # @raise [Runtime::TypeMismatch] if no receiver identity resolves for an explicit target
       # @raise [Runtime::UnknownArgument] if an explicit projection has an undeclared fact
-      # rubocop:disable-next Metrics/ParameterLists -- the keyword entry point both interpreters call
       def build(registry:, verb:, projected:, explicit:, passthrough: [], source_receiver: nil)
         args = projected.transform_keys(&:to_sym)
         return forwarded(registry, verb, args, source_receiver) unless explicit

data/lib/hecks/runtime/refusal_wording.rb

@@ -55,6 +55,15 @@ module Hecks
         render_with(template(refusal, site), specs, arguments)
       end
 
+      # Appends the command that creates an aggregate's records, when the bluebook declares one.
+      # The message is returned unchanged for an aggregate that declares no creator.
+      def with_creator_hint(message, aggregate)
+        creator = aggregate.created_by
+        return message if creator.nil? || creator.to_s.empty?
+
+        "#{message}: run #{creator} first"
+      end
+
       def refuse_wrong_arguments!(refusal, site, declared, offered)
         missing = declared - offered
         extra   = offered - declared
@@ -84,8 +93,10 @@ module Hecks
         items.empty? ? spec.fetch("when_empty") : items.join(spec.fetch("separator"))
       end
 
+      # The block form inserts each value as written: a replacement string would have `gsub` read
+      # its `\\`, `\0` and `\&` as escapes, so a quoted value's own backslash would collapse.
       def substitute(template, values)
-        values.reduce(template) { |text, (key, value)| text.gsub("{#{key}}", value.to_s) }
+        values.reduce(template) { |text, (key, value)| text.gsub("{#{key}}") { value.to_s } }
       end
 
       def template(refusal, site)

data/lib/hecks/runtime/registry/context_maps.rb

@@ -5,16 +5,12 @@ module Hecks
       module ContextMaps
         # Boot-time-only, single-threaded: it runs from Hecks.collect while a `.contextmap` file is
         # being Kernel.loaded, before the registry reaches a live, multi-threaded caller.
-        # rubocop:disable Hecks/ThreadSharedIvarMutation
         # Registers a declared context map under its system's name, a later one of the same name
         # replacing the earlier (a map is one declaration, not a layered overlay).
         #
         # @param item [Bluebook::ContextMap] the declared map
         # @return [Bluebook::ContextMap] the map
-        def add_context_map(item)
-          @declared.context_maps[item.name] = item
-        end
-        # rubocop:enable Hecks/ThreadSharedIvarMutation
+        def add_context_map(item) = @declared.store(:context_maps, item.name, item)
 
         # Finds a system's declared context map by name.
         #

data/lib/hecks/runtime/registry/declarations.rb

@@ -3,16 +3,46 @@ module Hecks
     class Registry
       # What a boot gathers while the `.bluebook`, `.hecksagon`, `.world` and `.contextmap` files
       # load: the bluebooks and their builders, the wiring, ports, adapters, worlds, translations,
-      # context maps, the eras the boot gate resolved, and the privacy markings still to be
-      # dispatched.
+      # context maps, the eras the boot gate resolved, the domains whose booted shape no era holds
+      # yet, the domains whose unheld shape one recorded move leads to, and the privacy markings
+      # still to be dispatched.
       Declarations = Struct.new(:bluebooks, :bluebook_sources, :hecksagons, :bounded_bluebooks, :ports,
                                 :adapters, :worlds, :translations, :bluebook_builders,
                                 :pending_privacy_markings, :resolved_eras, :superseded_eras,
-                                :context_maps) do
+                                :context_maps, :unminted_eras, :behind_eras) do
         # @return [Declarations] every collection empty
         def self.empty
-          new({}, {}, {}, {}, {}, {}, {}, [], {}, [], {}, {}, {})
+          new({}, {}, {}, {}, {}, {}, {}, [], {}, [], {}, {}, {}, {}, {})
         end
+
+        # Stores a value under a key in a keyed collection, and answers the value.
+        #
+        # @param collection [Symbol] the member holding the keyed collection
+        # @param key [Object] the key
+        # @param value [Object] the value to store
+        # @return [Object] `value`
+        def store(collection, key, value) = self[collection][key] = value
+
+        # Removes a key from a keyed collection.
+        #
+        # @param collection [Symbol] the member holding the keyed collection
+        # @param key [Object] the key to remove
+        # @return [Object, nil] the value removed, or nil when the key was absent
+        def remove(collection, key) = self[collection].delete(key)
+
+        # Appends a value to a list collection.
+        #
+        # @param collection [Symbol] the member holding the list
+        # @param value [Object] the value to append
+        # @return [Array] the list, `value` last
+        def append(collection, value) = self[collection] << value
+
+        # Records that a `.bluebook` file contributed to a bluebook name.
+        #
+        # @param name [String] the bluebook name
+        # @param path [String] the file that declared it
+        # @return [Array<String>] every path recorded for that name, `path` last
+        def record_source(name, path) = (bluebook_sources[name] ||= []) << path
       end
     end
   end

data/lib/hecks/runtime/registry/hecksagon_rules.rb

@@ -44,18 +44,32 @@ module Hecks
         def refuse_unwired_attachments!(hecksagon)
           hecksagon.attachments.each do |attachment|
             next if hecksagon(attachment.declaration_name)
+            next if contextmap_declares?(hecksagon, attachment)
 
             raise WiringError, unwired_attachment_message(hecksagon, attachment)
           end
         end
 
+        # A gem bluebook that the system's `.contextmap` names as a context needs no sibling
+        # hecksagon: its wiring is the attach itself. A vendored package still needs one, since
+        # its persistence and `translates` ACL can only be written there.
+        #
+        # @return [Boolean] true if the system's context map names the attached gem bluebook
+        def contextmap_declares?(hecksagon, attachment)
+          return false if attachment.vendor?
+
+          map = context_map(hecksagon.domain)
+          !map.nil? && map.context_names.include?(attachment.declaration_name.to_s)
+        end
+
         def unwired_attachment_message(hecksagon, attachment)
           declaration_name = attachment.declaration_name
           what = attachment.vendor? ? "vendored bluebook #{attachment.name.inspect}" : declaration_name.inspect
           "#{hecksagon.domain} attaches #{what} " \
             "(bounded context #{declaration_name}) but never declared " \
             "Hecks.hecksagon #{declaration_name.inspect} — put that sibling " \
-            "(and any `translates` ACL) in context_map.hecksagon; " \
+            "(and any `translates` ACL) in context_map.hecksagon, or name the context in " \
+            "#{hecksagon.domain}'s `.contextmap` (gem bluebooks only); " \
             "same-name blocks merge, order-independent."
         end
 

data/lib/hecks/runtime/registry/runtime_state.rb

@@ -22,6 +22,16 @@ module Hecks
         def clear
           to_a.each(&:clear)
         end
+
+        # Logs one reaction's outcome, and the event instance it answered when known.
+        #
+        # @param record [Hash{Symbol => Object}] the reaction's outcome
+        # @param event [String, Integer, nil] the event instance, or nil when not known
+        # @return [void]
+        def log_reaction(record, event)
+          reaction_log << record
+          reaction_events[record] = event if event
+        end
       end
     end
   end

data/lib/hecks/runtime/registry/world_defaults.rb

@@ -8,9 +8,31 @@ module Hecks
         AGGREGATE_PLACEHOLDER = /\{(name|storage_name)\}/
 
         # The default database only reaches a persistence bind whose adapter declares a
-        # `database` field; a `database` the bluebook's own settings name always wins.
+        # `database` field; a `database` the bluebook's own settings name always wins. Every
+        # value the adapter declares as a secret is held by `Secrets` on the way, so no text the
+        # launcher prints can carry it.
         def binding_settings(domain, verb, adapter)
           declared = world(domain)&.for_binding(verb, adapter) || {}
+          settings = with_world_mint_names(domain, verb, adapter, with_default_database(domain, verb, adapter, declared))
+          Secrets.register_settings(@declared.adapters[adapter.to_s], settings)
+          settings
+        end
+
+        # The commands a world names at its top level (`minting commands: [...]`) join the names a
+        # persistence block gives, for an adapter that declares `mints_era`: a domain whose binding
+        # lives in uncommitted local files still has a committed place to say them.
+        def with_world_mint_names(domain, verb, adapter, settings)
+          return settings unless mint_names_apply?(verb, adapter)
+
+          named = Array(world(domain)&.for_verb("minting")&.fetch(:commands, nil)).map(&:to_s)
+          named.empty? ? settings : settings.merge(mints_era: (Ports::Persistence::MintDoor.names(settings) + named).uniq)
+        end
+
+        def mint_names_apply?(verb, adapter)
+          verb.to_s == Ports::Persistence::VERB && @declared.adapters[adapter.to_s]&.declares?(:mints_era)
+        end
+
+        def with_default_database(domain, verb, adapter, declared)
           database = default_database_for(domain)
           return declared unless database && default_database_applies?(verb, adapter)
 
@@ -28,7 +50,7 @@ module Hecks
 
             verify_default_adapter_named!(declared.domain, name)
           end
-          self
+          apply_world_names!
         end
 
         # The defaults an adapter's `.adapter` declares for its fields, with each `{name}` or