hecks 0.2.0 → 0.3.0

data/lib/hecks/router.rb

@@ -0,0 +1,70 @@
+module Hecks
+  # The public, project-wide dispatch door. It owns address resolution only;
+  # each discovered Bluebook keeps its own runtime and persistence bindings.
+  class Router
+    class UnknownAddress < StandardError; end
+    class WrongVerbKind < StandardError; end
+    class NotBooted < StandardError; end
+    class AmbiguousShortRoute < StandardError; end
+
+    attr_reader :register
+
+    def self.load(root) = new(Bluebook::ProjectLoader.load(root))
+
+    # Install one project router for ordinary application calls. The explicit
+    # `Router.load` API remains useful for tests and embedded hosts.
+    def self.boot(root)
+      router = load(root)
+      router.install_namespace!
+      @default = router
+    end
+
+    def self.default
+      @default || raise(NotBooted, "no project router is booted — call Hecks::Router.boot(root) first")
+    end
+
+    def self.dispatch(address, **args) = default.dispatch(address, **args)
+    def self.query(address, **args)    = default.query(address, **args)
+
+    def initialize(register)
+      @register = register
+    end
+
+    def available = register.entries.values
+
+    def install_namespace! = NamespaceInstaller.new(self).install!
+
+    def resolve(address)
+      fqn = Fqn.parse(address)
+      raise UnknownAddress, "router addresses require a realm: #{address.inspect}" unless fqn.realm
+
+      register.fetch(fqn.to_s)
+    rescue KeyError
+      raise UnknownAddress, "no Bluebook route for #{address.inspect}"
+    end
+
+    def dispatch(address, **args)
+      entry = resolve(address)
+      raise WrongVerbKind, "#{address.inspect} names a query; use #query" unless entry.command?
+
+      entry.dispatcher.dispatch(local_verb(entry), **args)
+    end
+
+    def query(address, **args)
+      entry = resolve(address)
+      raise WrongVerbKind, "#{address.inspect} names a command; use #dispatch" unless entry.query?
+
+      entry.dispatcher.query(local_verb(entry), **args)
+    end
+
+    private
+
+    def local_verb(entry)
+      return "#{entry.fqn.domain}.#{entry.declared_verb}" unless entry.fqn.aggregate
+
+      "#{entry.fqn.domain}::#{entry.fqn.aggregate}.#{entry.declared_verb}"
+    end
+  end
+end
+
+require_relative "router/namespace_installer"

data/lib/hecks/runtime/caller.rb

@@ -0,0 +1,50 @@
+module Hecks
+  module Runtime
+    # WHO IS DISPATCHING, bound for the duration of a block — the ambient
+    # counterpart to `Runtime.with_registry`, but `Thread.current`-backed
+    # rather than a plain module ivar: registry-binding happens at BOOT
+    # time (single-threaded by construction), this happens at DISPATCH
+    # time, which a future per-request caller (docs/rails-integration.md's
+    # still-unbuilt `WebDoor`) needs to bind safely under concurrency.
+    #
+    # A child `Thread.new` spawned mid-block does not inherit this — plain
+    # Ruby thread-local semantics — but nothing in this codebase spawns a
+    # worker thread mid-dispatch today, so this is a fact worth naming
+    # rather than a gap worth solving.
+    module Caller
+      # `actor_id` is OPTIONAL, on top of the role that has always been
+      # here — a caller that states only a role (every caller before this)
+      # is checked the way it always was, string equality against the
+      # command's own `role`. A caller that also names WHO it is lets
+      # `CommandRules::Authorization` check a real Governance
+      # `RoleAssignment` instead, once the command's domain has Governance
+      # attached — see that module's own header for the full split.
+      Current = Struct.new(:role, :actor_id, keyword_init: true)
+
+      module_function
+
+      def current = Thread.current[:hecks_caller]
+
+      def as(role:, actor_id: nil)
+        previous = Thread.current[:hecks_caller]
+        Thread.current[:hecks_caller] = Current.new(role: role.to_s, actor_id: actor_id&.to_s)
+        yield
+      ensure
+        Thread.current[:hecks_caller] = previous
+      end
+
+      # A REACTION IS THE SYSTEM ACTING, not the caller who happened to be
+      # on the stack when the triggering command ran — `Dispatcher#reenter`
+      # clears the ambient caller around a reaction's own dispatch so a
+      # triggering caller's role can neither satisfy nor block a reaction
+      # command it has nothing to do with.
+      def without
+        previous = Thread.current[:hecks_caller]
+        Thread.current[:hecks_caller] = nil
+        yield
+      ensure
+        Thread.current[:hecks_caller] = previous
+      end
+    end
+  end
+end

data/lib/hecks/runtime/capability_graph.rb

@@ -0,0 +1,44 @@
+module Hecks
+  module Runtime
+    # WHICH PORTS A BOOT CAN ACTUALLY FULFILL, read off the registry it already
+    # holds. `registry.ports` names every port a domain declared a dependency
+    # on ; `registry.adapters` names every adapter wired to implement one — the
+    # same `adapter.port == port.name` match `Ports::Extraction` and
+    # `Ports::IdentityGeneration` already make for themselves, one at a time,
+    # each time they resolve. This is that same question asked once, for
+    # every port at once, so a gap in the wiring is something a caller can ASK
+    # about rather than something a live dispatch discovers by refusing.
+    #
+    # `cycles` answers `[]`, always, and honestly: nothing in this port model
+    # lets one port depend on another — a port names a verb and a signal, an
+    # adapter names the port it implements, and neither can point at a third
+    # port. There is no edge for a cycle to be made of.
+    class CapabilityGraph
+      def initialize(registry)
+        @registry = registry
+      end
+
+      # { port name => [adapter name, ...] }, for every port the registry
+      # declares — including the ports nothing implements, so a caller can
+      # tell "declared, unfulfilled" from "never declared at all".
+      def fulfillments
+        @fulfillments ||= @registry.ports.each_key.to_h { |name| [name, adapters_for(name)] }
+      end
+
+      # The ports with zero adapters bound — the gap `Runtime::WiringError`
+      # would otherwise only surface at the moment something tries to dispatch
+      # through one.
+      def unfulfilled
+        fulfillments.select { |_, adapters| adapters.empty? }.keys
+      end
+
+      def cycles = []
+
+      private
+
+      def adapters_for(port_name)
+        @registry.adapters.values.select { |adapter| adapter.port == port_name }.map(&:name)
+      end
+    end
+  end
+end

data/lib/hecks/runtime/command_interpreter/argument_gate.rb

@@ -0,0 +1,124 @@
+require_relative "../../naming"
+require_relative "../errors"
+require_relative "../refusal_wording"
+
+module Hecks
+  module Runtime
+    class CommandInterpreter
+      # The payload gate: a command takes the arguments it declares — all of
+      # them, and no others.
+      module ArgumentGate
+        private
+
+        # Anything else used to ride along in the payload untouched —
+        # normalize_args walks the DECLARED attributes, so a name the command
+        # never had was simply never looked at. A misspelled argument did
+        # nothing, in silence.
+        #
+        # The keys that are legitimately not attributes are the ones that ADDRESS
+        # the aggregate rather than describe it : `id`, whatever the aggregate is
+        # identified by, and the reference key of the root a command reaches
+        # through. Refusing those would refuse every dispatch there is.
+        def refuse_unknown_arguments(domain, aggregate, command, args)
+          addressing = [:id, *aggregate.identity_heads, reference_key(command)] + correlation_keys(domain)
+          known      = (command.attributes.map(&:name) + addressing).compact.map(&:to_sym)
+          # SORTED. Payload order is whatever the caller happened to write, and
+          # refusal wording is contract — pinned byte-for-byte by the corpus, so
+          # it cannot depend on hash iteration order.
+          unknown = (args.keys.map(&:to_sym) - known).sort
+          return if unknown.empty?
+
+          raise UnknownArgument,
+                RefusalWording.render("UnknownArgument", "unknown_args",
+                                      command: command.hecks_name, unknown: unknown.join(", "),
+                                      declared: declared_reading(command))
+        end
+
+        # And it takes ALL of them. The other half of the same sentence, missing
+        # until fuzz went looking : a name the command never declared was refused,
+        # while a name it DID declare could simply be left out.
+        #
+        # `Customer.Register` without its `name` used to be refused — but by
+        # ACCIDENT, and with a lie for a message. `then_set :name, to: :name` found
+        # nothing to resolve, passed the literal symbol on, and coercion reported
+        # `name is a PersonName — pass its fields as an object`, which describes a
+        # mistake the caller did not make. The real mistake — an argument simply
+        # missing — was never the one named, and nothing refused it on purpose.
+        #
+        # No command attribute anywhere in the corpus carries a default — checked,
+        # all eight chapters, zero — so there is no optional argument for this to
+        # step on. Every declared attribute is a fact the command needs.
+        #
+        # `aggregate:` — PRESENT ONLY FOR A PORT OPERATION. An aggregate
+        # command's own self-address never reaches this list at all
+        # (`CommandBuilder#reference_to`'s bare self-reference mints no
+        # attribute to be absent) — but `PortOperationBuilder#reference_to`
+        # ALWAYS mints one (this file's own header on `PortOperation`: "no
+        # creates?/acts_on distinction to protect"), because an operation
+        # historically had no OTHER way to say which record it addressed.
+        # `to:` is that other way now (`Dispatcher#port_invocation`
+        # promotes the identity attribute's own value out of the payload
+        # and into routing) — which left the attribute still DECLARED,
+        # still non-optional, and now never present in `args` at all: every
+        # operation with an identity attribute refused its own well-formed
+        # calls, dispatched exactly the way `to:` intends. Exempted here on
+        # the same terms an aggregate command's self-address always was —
+        # an address, not a fact the operation still needs handed back.
+        def refuse_absent_arguments(command, args, aggregate: nil)
+          given    = args.keys.map(&:to_sym)
+          exempt   = aggregate && command.respond_to?(:identity_attribute) &&
+                     command.identity_attribute(aggregate.hecks_name)&.name
+          required = command.attributes.reject(&:optional?).map { |attribute| attribute.name.to_sym } - [exempt]
+          # SORTED, for the same reason the unknown list is : refusal wording is
+          # contract, and a pinned wording cannot depend on the order a set
+          # difference happens to be computed in.
+          absent = (required - given).sort
+          return if absent.empty?
+
+          raise AbsentArgument,
+                RefusalWording.render("AbsentArgument", "absent_args",
+                                      command: command.hecks_name, absent: absent.join(", "),
+                                      declared: declared_reading(command))
+        end
+
+        # A COMMAND THAT DECLARES NOTHING STILL HAS TO SAY SO. `Account
+        # .Freeze` is `reference_to Account` and no attributes at all, so
+        # `{declared}` rendered empty and the sentence trailed off mid-
+        # clause : "Freeze does not declare standing — it takes ". Read
+        # against a real refusal that shape is worse than unhelpful — it
+        # looks like the message itself is broken, right where a caller
+        # is already trying to work out what went wrong.
+        #
+        # Only the empty case changes. Every command that declares even
+        # one attribute renders exactly as it did before, because refusal
+        # wording is contract and pinned byte-for-byte by the corpus (see
+        # `refuse_unknown_arguments`' own note on sorting for why).
+        def declared_reading(command)
+          declared = command.attributes.map(&:name)
+          declared.empty? ? "none" : declared.join(", ")
+        end
+
+        # What a process manager correlates by is ROUTING, not description. A saga
+        # threads its correlation key through every leg it dispatches so the event
+        # each leg emits carries it and the next step can be correlated — so the key
+        # arrives on commands that never declare it, and legitimately.
+        #
+        # This is the weakest part of the gate. Correlation is the SAGA's business,
+        # and the better shape is for the saga to stamp its own key onto the event
+        # it caused rather than smuggle it through the command's payload. Until it
+        # does, refusing the key here would break every saga in the corpus.
+        def correlation_keys(domain)
+          Array(@registry.bluebook(domain)&.process_managers)
+            .filter_map { |saga| saga.correlates_by && saga.correlation_head }
+        end
+
+        def reference_key(command)
+          target = command.references.to_s
+          return nil if target.empty?
+
+          Naming.reference_key(target)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/command_interpreter/mutation_applier.rb

@@ -0,0 +1,248 @@
+require_relative "../value"
+
+module Hecks
+  module Runtime
+    class CommandInterpreter
+      # How a command's declared mutations land on the instance in hand —
+      # set, append (with value-object or entity elements), and the
+      # arithmetic pair.
+      module MutationApplier
+        private
+
+        def assign_creation_attributes(instance, aggregate, command, args)
+          command.attributes.each do |attr|
+            next unless aggregate.attribute(attr.name)
+            next unless args.key?(attr.name)
+
+            instance[attr.name] = Value.for(aggregate, attr.name, args[attr.name])
+          end
+        end
+
+        def apply(instance, aggregate, mutation, args)
+          case mutation.op
+          when :set
+            value = mutation.source.is_a?(StateRef) ? instance[mutation.source.name] : @rules.resolve_source(mutation.source, args)
+            instance[mutation.target] = Value.for(aggregate, mutation.target, value)
+          when :append
+            instance[mutation.target] = appended(instance, aggregate, mutation, args)
+          when :increment, :decrement
+            amount = @rules.resolve_source(mutation.source, args)
+            attribute = aggregate.attribute(mutation.target)
+            current   = instance[mutation.target]
+            # Vendored fix, not (yet) upstream hecks (migration plan
+            # task 9): see #rewrap_arithmetic_result's own comment below
+            # -- `amount` is wrapped ONLY when `current` already is, not
+            # merely because the target attribute exists.
+            amount = Value.for_attribute(aggregate, attribute, amount) if attribute && current.is_a?(Value)
+            result = @rules.arithmetic(current, amount, mutation.target, @rules.sign_of(mutation.op))
+            instance[mutation.target] = rewrap_arithmetic_result(aggregate, attribute, current, result)
+          # Vendored addition, not (yet) upstream hecks (migration
+          # plan task 4): remove -- the list-removal counterpart to
+          # append, matching an element by value (plan.bluebook's
+          # RemoveDependency/DeactivateSprint: "a concurrent Add can
+          # never be lost").
+          when :remove
+            instance[mutation.target] = removed(instance, aggregate, mutation, args)
+          # Vendored addition, not (yet) upstream hecks (migration
+          # plan task 4, i106): multiply/clamp, the scale/bound pair
+          # alongside increment/decrement's add/subtract pair -- see
+          # CommandRules::Arithmetic#multiply/#clamp's own comments.
+          when :multiply
+            amount = @rules.resolve_source(mutation.source, args)
+            attribute = aggregate.attribute(mutation.target)
+            current   = instance[mutation.target]
+            amount = Value.for_attribute(aggregate, attribute, amount) if attribute && current.is_a?(Value)
+            result = @rules.multiply(current, amount, mutation.target)
+            instance[mutation.target] = rewrap_arithmetic_result(aggregate, attribute, current, result)
+          # Vendored addition, not (yet) upstream hecks (migration
+          # plan task 4, i106): clamp -- bounds the current value into
+          # [min, max]. mutation.source is always a literal [min, max]
+          # pair, never an argument reference -- resolve_source would be
+          # a no-op for an Array (it only special-cases Symbol), so it's
+          # read straight.
+          when :clamp
+            instance[mutation.target] = @rules.clamp(instance[mutation.target], mutation.source, mutation.target)
+          # `delegates_to` — CommandBuilder#delegates_to's own comment gives
+          # the full reasoning for storing it as a mutation at all. A REAL
+          # no-op here, not a gap: it targets no field on THIS instance —
+          # `CommandInterpreter#step_delegate_to_entity`, a LATER step in
+          # the same dispatch, is what actually applies it, against the
+          # target entity element `EntityElement.apply_to_element` reaches,
+          # never through this method.
+          when :delegate
+            nil
+          else
+            # Every declared op has a `when` above — this is not a real
+            # runtime path today, only a backstop against the day one
+            # more mutation kind reaches the grammar and this method,
+            # unlike every other one it could reach, does not: applying
+            # nothing and refusing nothing would be the one silent
+            # no-op in a language that otherwise refuses what it cannot
+            # check.
+            raise Runtime::WiringError, "no mutation applier handles :#{mutation.op} — add one before declaring it"
+          end
+        end
+
+        # A CALLER-SUPPLIED ARG, FIRST -- an append's own field can also
+        # name something the SUBJECT ALREADY KNOWS about itself, falling
+        # back to the AGGREGATE'S OWN CURRENT FIELD when it isn't one — a
+        # caller appending at the end without computing or supplying a
+        # position (`position: :next_position`, a field the command never
+        # declares as an argument at all). `args.key?`, not a truthiness
+        # check on the value — an explicitly-nil argument still counts as
+        # "the caller named it," same distinction `assign_creation_attributes`
+        # already draws.
+        #
+        # Extracted to its own method (pure refactor, ternary -> early
+        # return, no behavior change) alongside `remove`'s own addition
+        # below, purely for readability at this point in the file.
+        def resolve_append_source(source, instance, args)
+          # `state(:field)` — the record's own value, never an argument
+          # (`Literal::StateRef`'s own comment).
+          return instance[source.name] if source.is_a?(StateRef)
+          return source unless source.is_a?(Symbol)
+          return args[source] if args.key?(source)
+
+          instance[source]
+        end
+
+        def appended(instance, aggregate, mutation, args)
+          fields       = mutation.source.transform_values { |source| resolve_append_source(source, instance, args) }
+          element_type = aggregate.attribute(mutation.target)&.type
+          value_object = aggregate.value_object(element_type)
+          if value_object
+            value_object.attributes.each do |attribute|
+              held = fields[attribute.name]
+              # A SINGLE-FIELD VALUE unwraps to its scalar so it bridges
+              # into the element's own (differently named) wrapper; a
+              # MULTI-FIELD one (a `state(:en_passant_square)` Square
+              # copied off the record) has no scalar to stand in for it
+              # and is handed across whole — `Value.for_attribute` keeps a
+              # value of the element field's own type as it is.
+              fields[attribute.name] = Value.scalar(held) if held.is_a?(Value) && held.to_h.size == 1
+            end
+          end
+          element = value_object ? Value.build(value_object, fields,
+                                               aggregate) : entity_element(aggregate, element_type, instance[mutation.target],
+                                                                           fields)
+
+          # FROZEN, like every other value the domain hands back. An
+          # appended list used to come back mutable, so a caller could
+          # push straight into an aggregate's own state after the
+          # dispatch had finished.
+          Freezer.deep(Array(instance[mutation.target]) + [element])
+        end
+
+        # Vendored addition, not (yet) upstream hecks (migration plan
+        # task 4): the removal counterpart to #appended -- matches by
+        # VALUE EQUALITY, element-wise, no read-modify-write (plan.
+        # bluebook's own words: "so a concurrent Add can never be lost").
+        # `mutation.source` is a single field reference (`:dependency`),
+        # unlike append's field-map -- resolved and Value-coerced the
+        # SAME way increment/decrement already coerce their own amount,
+        # so the comparison is against a like-shaped Value, not a raw
+        # scalar against a wrapped one.
+        def removed(instance, aggregate, mutation, args)
+          value     = @rules.resolve_source(mutation.source, args)
+          attribute = aggregate.attribute(mutation.target)
+          value     = Value.for_attribute(aggregate, attribute, value) if attribute
+          Array(instance[mutation.target]).reject { |element| element == value }
+        end
+
+        # Vendored fix, not (yet) upstream hecks (migration plan
+        # task 9): #apply's `:increment`/`:decrement`/`:multiply`
+        # branches used to wrap `amount` into a `Value` unconditionally
+        # whenever the target attribute existed, never checking whether
+        # `current` (the field's OWN existing value, read straight off
+        # `instance[mutation.target]`) was ALSO wrapped -- the two sides
+        # of the same arithmetic call could disagree on Value-ness. On a
+        # PHANTOM-CREATED field this is the common case, not an edge
+        # one: `Instance.defaults`/`#default_for` leaves a VO-typed
+        # attribute with no declared `default:` genuinely absent (nil),
+        # and `CommandRules::Arithmetic#arithmetic`/`#multiply`'s own
+        # `current ||= 0` then turns that nil into a RAW, unwrapped
+        # Integer `0` -- so `current.is_a?(Value) && amount.is_a?(Value)`
+        # read false even though `amount` (correctly wrapped by the old
+        # unconditional line) genuinely held a valid, correctly-typed
+        # number, and the primitive path's `unless amount.is_a?(Numeric)`
+        # guard refused it as a TYPE MISMATCH the caller never made --
+        # an artifact of this method's own asymmetric wrapping, not bad
+        # input.
+        #
+        # Fixed at the call site (above) by wrapping `amount` ONLY when
+        # `current` is ALREADY a `Value` -- so an established VO-typed
+        # field (a multi-field Money balance, say, already hydrated from
+        # a prior save) keeps going through
+        # `Arithmetic#arithmetic_value_object` exactly as before (the
+        # "already-Value-wrapped field still mutates correctly" case
+        # this fix must not regress), while a phantom field's raw
+        # `current` and raw `amount` both take the plain-Numeric path
+        # together. This method closes the other half: the plain-Numeric
+        # path returns a bare Ruby number, and if the attribute is
+        # itself VO-typed (the norm), that raw result needs the SAME
+        # wrap `:set` already gives its own resolved value (`Value.for`)
+        # before it's stored, so a field's stored shape doesn't depend
+        # on which dispatch happened to mutate it first. A no-op
+        # whenever `current` was already a Value (the VO branch already
+        # returns one) or the mutation targets no declared attribute at
+        # all.
+        def rewrap_arithmetic_result(aggregate, attribute, current, result)
+          return result if current.is_a?(Value) || attribute.nil? || result.is_a?(Value)
+
+          Value.for_attribute(aggregate, attribute, result)
+        end
+
+        def entity_element(aggregate, element_type, current, fields)
+          entity = aggregate.entities.find { |piece| piece.hecks_name == element_type.to_s }
+          return fields unless entity
+
+          entity.attributes.each do |attribute|
+            next unless fields.key?(attribute.name)
+
+            fields[attribute.name] = Value.for_attribute(aggregate, attribute, fields[attribute.name])
+          end
+          if entity.identified_by && !fields.key?(entity.identified_by)
+            attribute = entity.attribute(entity.identified_by)
+            fields[entity.identified_by] = Value.from_identifier(aggregate, attribute, Array(current).size + 1)
+          else
+            check_entity_collision(aggregate, entity, current, fields)
+          end
+          fields[entity.lifecycle.field] ||= entity.lifecycle.default if entity.lifecycle
+          fields
+        end
+
+        # THE SAME CHECK #hydrate GIVES EVERY CREATING AGGREGATE COMMAND
+        # (`repository.find(id)`, above this file in command_interpreter.rb),
+        # one level down. Reached only on the two branches #entity_element
+        # does NOT auto-mint: a CALLER-SUPPLIED identity (the field is
+        # already in the append's own field map, so the `if` above skips
+        # it) or a COMPOSITE one (`entity.identified_by` is nil for those —
+        # Runtime::Identified#derive_identity — so the `if` above is false
+        # unconditionally). Neither used to check the sibling list at all:
+        # a second LogVisit with the same date+sequence, or a second
+        # IssueKey with the same serial, appended a silent duplicate — worse
+        # than an ordinary duplicate row, because EntityInterpreter#element_of's
+        # `find_index` always matches the FIRST match, so the second becomes
+        # permanently unaddressable by any later command.
+        #
+        # Auto-minted entities never reach here — `identity_heads` for them
+        # is still checked at mint time by construction (`current.size + 1`
+        # can only repeat if something `remove:`s from the list between
+        # mints, which no real domain does today), so they can't be flagged
+        # by mistake.
+        def check_entity_collision(aggregate, entity, current, fields)
+          heads = entity.identity_heads
+          return if heads.empty?
+
+          collision = Array(current).find { |element| heads.all? { |head| element[head] == fields[head] } }
+          return unless collision
+
+          raise(AlreadyExists, RefusalWording.render("AlreadyExists", "entity_duplicate",
+                                                     entity: entity.hecks_name, aggregate: aggregate.hecks_name,
+                                                     identity: Identity.reading(entity),
+                                                     offered: heads.map { |head| Rendering.describe(fields[head]) }.join(", ")))
+        end
+      end
+    end
+  end
+end