hecks 0.2.0 → 1.0.0

data/lib/hecks/router/namespace_installer.rb

@@ -0,0 +1,157 @@
+require_relative "../fqn"
+require_relative "../facade/handle"
+
+module Hecks
+  class Router
+    # Installs optional Ruby syntax over an already-loaded router. FQN
+    # resolution stays in Router; this object only adapts it to constants and
+    # method calls.
+    class NamespaceInstaller
+      class OptionsProxy
+        def initialize(router:, realm:, domain:, aggregate:, options:)
+          unknown = options.keys - [:version]
+          raise ArgumentError, "unknown router options: #{unknown.join(', ')}" unless unknown.empty?
+
+          @router, @realm, @domain, @aggregate = router, realm, domain, aggregate
+          @version = options[:version]&.to_s
+        end
+
+        def method_missing(verb, **args)
+          fqn = fqn_for(verb)
+          fqn.command? ? @router.dispatch(fqn.to_s, **args) : @router.query(fqn.to_s, **args)
+        end
+
+        def respond_to_missing?(verb, include_private = false)
+          Fqn.command_name?(verb) || Fqn.query_name?(verb) || super
+        end
+
+        private
+
+        def fqn_for(verb)
+          if Fqn.command_name?(verb)
+            Fqn.command(realm: @realm, domain: @domain, version: @version, aggregate: @aggregate, command: verb)
+          elsif Fqn.query_name?(verb)
+            Fqn.query(realm: @realm, domain: @domain, version: @version, aggregate: @aggregate, query: verb)
+          else
+            raise NoMethodError, "#{verb.inspect} is not a Bluebook command or query"
+          end
+        end
+      end
+
+      def initialize(router)
+        @router = router
+      end
+
+      def install!
+        current_entries.each { |entry| install_namespace_entry(entry) }
+        install_shortcuts!
+        install_aggregate_doors!
+        self
+      end
+
+      private
+
+      attr_reader :router
+
+      def current_entries = router.available.reject { |entry| entry.fqn.version }
+
+      def install_namespace_entry(entry)
+        target  = namespace_for(entry.fqn.realm, entry.fqn.domain, entry.fqn.aggregate)
+        address = entry.fqn.to_s
+        active_router = router
+        target.define_singleton_method(:options) do |**options|
+          OptionsProxy.new(router: active_router, realm: entry.fqn.realm, domain: entry.fqn.domain,
+                           aggregate: entry.fqn.aggregate, options: options)
+        end
+        if entry.command?
+          target.define_singleton_method(entry.fqn.verb) { |**args| active_router.dispatch(address, **args) }
+        else
+          target.define_singleton_method(entry.fqn.verb) { |**args| active_router.query(address, **args) }
+        end
+      end
+
+      # `.find`/`.all`/`.count`/`.events`/`.repository` — the SAME read/CRUD
+      # surface `Facade::Surface::AggregateDoor` gives a plain `Hecks
+      # .boot`, missing here until now: `install_namespace_entry` above
+      # installs ONE method per declared VERB, so an aggregate with no
+      # commands or queries of its own shape (or simply never asked for
+      # a `find`-shaped query) had no way to look up one record by id
+      # through the router surface at all — real gap, hit live building
+      # a `List` aggregate meant to be read this way. Grouped by
+      # (realm, domain, aggregate) rather than installed per-verb,
+      # because unlike a command or query this is the SAME five methods
+      # regardless of which verb happened to trigger this aggregate's
+      # own namespace module into existing.
+      def install_aggregate_doors!
+        current_entries.reject { |entry| entry.fqn.aggregate.nil? }
+                       .group_by { |entry| [entry.fqn.realm, entry.fqn.domain, entry.fqn.aggregate] }
+                       .each_value { |entries| install_aggregate_door(entries.first) }
+      end
+
+      def install_aggregate_door(entry)
+        dispatcher = entry.dispatcher
+        domain     = entry.fqn.domain
+        ir         = dispatcher.registry.bluebook(domain)&.aggregate(entry.fqn.aggregate)
+        return unless ir # a query/command-only entry whose owner isn't a real aggregate root
+
+        fqn    = "#{domain}::#{ir.hecks_name}"
+        target = namespace_for(entry.fqn.realm, domain, entry.fqn.aggregate)
+
+        target.define_singleton_method(:repository) { dispatcher.registry.repository(domain, ir) }
+        target.define_singleton_method(:count)      { dispatcher.registry.repository(domain, ir).count }
+        target.define_singleton_method(:events)     { dispatcher.events.select { |event| event.aggregate == fqn } }
+
+        target.define_singleton_method(:find) do |id|
+          found = dispatcher.registry.repository(domain, ir).find(id)
+          found && Facade::Handle.new(dispatcher: dispatcher, domain: domain, ir: ir, instance: found)
+        end
+
+        target.define_singleton_method(:all) do
+          dispatcher.registry.repository(domain, ir).all.map do |instance|
+            Facade::Handle.new(dispatcher: dispatcher, domain: domain, ir: ir, instance: instance)
+          end
+        end
+      end
+
+      def install_shortcuts!
+        installer = self
+        current_entries.reject { |entry| entry.fqn.aggregate.nil? }
+                       .group_by { |entry| [entry.fqn.aggregate, entry.fqn.verb] }
+                       .each do |(aggregate, verb), candidates|
+          shortcut_target(aggregate).define_singleton_method(verb) { |**args|
+            installer.send(:dispatch_short, candidates, **args)
+          }
+        end
+      end
+
+      def dispatch_short(candidates, **args)
+        if candidates.length > 1
+          shown = candidates.map { |entry| entry.fqn.to_s }.sort.join(", ")
+          aggregate, verb = candidates.first.fqn.aggregate, candidates.first.fqn.verb
+          raise AmbiguousShortRoute, "#{aggregate}.#{verb} is ambiguous — choose one of: #{shown}"
+        end
+
+        entry = candidates.fetch(0)
+        entry.command? ? router.dispatch(entry.fqn.to_s, **args) : router.query(entry.fqn.to_s, **args)
+      end
+
+      def shortcut_target(aggregate)
+        constant = Object.const_get(aggregate, false) if Object.const_defined?(aggregate, false)
+        raise NameError,
+              "cannot install Bluebook shortcut #{aggregate}: it is not a module" if constant && !constant.is_a?(Module)
+
+        constant || Object.const_set(aggregate, Module.new)
+      end
+
+      def namespace_for(realm, domain, aggregate)
+        [realm, domain, aggregate].compact.reduce(Object) do |parent, name|
+          constant = parent.const_get(name, false) if parent.const_defined?(name, false)
+          raise NameError,
+                "cannot install Bluebook route under #{parent}::#{name}: it is not a module" if constant && !constant.is_a?(Module)
+
+          constant || parent.const_set(name, Module.new)
+        end
+      end
+    end
+  end
+end

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/aggregate_lock.rb

@@ -0,0 +1,45 @@
+module Hecks
+  module Runtime
+    # A PROCESS-WIDE, STRIPED MUTEX REGISTRY — the concurrency-control
+    # mechanism for every adapter that does NOT declare
+    # `:optimistic_concurrency` (Heki, Memory today; see
+    # `CommandInterpreter#call`/`EntityInterpreter#call`, which choose
+    # between this and Postgres's CAS+retry purely off
+    # `repository.capabilities`).
+    #
+    # WHY A LOCK SUFFICES HERE AND CAS IS NOT NEEDED: both adapters hold
+    # process-local data. `Adapters::Memory.tenant_capable?`'s own comment
+    # states the confirmed fact this relies on — two `Runtime.boot` calls
+    # get two entirely separate adapter instances; there is never a SECOND
+    # PROCESS writing the same Heki file or the same Memory Hash, only
+    # possibly other THREADS within this one process. A `Mutex` held for
+    # the full hydrate-through-save critical section closes the identical
+    # lost-update gap CAS closes for Postgres, with no schema, no version
+    # column, and no retry loop — the second thread simply doesn't start
+    # its own hydrate until the first thread's save has landed.
+    #
+    # STRIPED, NOT ONE GLOBAL LOCK: keyed by `[domain, aggregate.hecks_name,
+    # id]`, so two dispatches against two DIFFERENT records never block
+    # each other. The registry Hash itself is guarded by its own top-level
+    # Mutex only for the moment a new per-key Mutex is created — two
+    # threads locking DIFFERENT keys for the first time never wait on one
+    # another beyond that brief creation window.
+    module AggregateLock
+      @registry_lock = Mutex.new
+      @locks = {}
+
+      class << self
+        # `AggregateLock.for(domain, aggregate, id).synchronize { ... }`
+        # `id: nil` — identity could not be resolved yet (see
+        # `Identity.best_effort`) — locks by aggregate TYPE alone, coarser
+        # (every record of this aggregate serializes against every other)
+        # but still correct: it can only ever make dispatch MORE
+        # conservative than a resolved id would.
+        def for(domain, aggregate, id = nil)
+          key = id.nil? ? [domain.to_s, aggregate.hecks_name] : [domain.to_s, aggregate.hecks_name, id.to_s]
+          @registry_lock.synchronize { @locks[key] ||= Mutex.new }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/boot_gates.rb

@@ -0,0 +1,41 @@
+module Hecks
+  module Runtime
+    # A boot's own small set of phase-tagged, conditionally-present gates —
+    # ADR 0031. Registration is instance-scoped, ONE PER `Loader.boot`
+    # CALL, never a module-level singleton: a process that boots more than
+    # one registry in its lifetime (every spec suite does) must never let
+    # one boot's capability profile leak into the next boot's gate list.
+    #
+    # A gate is anything `.call(registry, directory)`-able — an existing
+    # module method handed over as a `Method` object (`EraCheck.method
+    # (:check_lineage!)`) needs no wrapper; a bare block does. Phases run
+    # in the order `run!` is called, gates within a phase in registration
+    # order — today exactly one gate per phase, so ordering among
+    # same-phase gates has never been exercised.
+    #
+    # This is deliberately NOT the same registry `Hecks::Projector` uses
+    # (ADR 0027) — that one is a process-wide, static IR-in/artifact-out
+    # registry with no bindings and no live-state mutation; this one is
+    # per-boot and gates real I/O (a Postgres mint, a saga-store read).
+    # Sharing a primitive between them is deferred until a third consumer
+    # actually wants it (0031's own Rejected Alternatives).
+    class BootGates
+      def initialize
+        @gates = Hash.new { |h, k| h[k] = [] }
+      end
+
+      def register(name, gate, phase:)
+        @gates[phase] << [name, gate]
+        self
+      end
+
+      def registered?(name)
+        @gates.values.flatten(1).any? { |registered_name, _gate| registered_name == name }
+      end
+
+      def run!(phase, registry, directory)
+        @gates[phase].each { |pair| pair.last.call(registry, directory) }
+      end
+    end
+  end
+end

data/lib/hecks/runtime/caller.rb

@@ -0,0 +1,66 @@
+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.
+      #
+      # `as_of` and `scope` are BOTH optional too, and both self-asserted
+      # by the caller rather than derived from the command — deliberately:
+      # `as_of` is filled at the door from `Ports::Clock.now`, never
+      # inside the interpreter (see `Ports::Clock`'s own header), so
+      # there is no other place to source it from. `scope` stays here
+      # rather than becoming a command-level DSL construct on purpose —
+      # a scope check that lived in the bluebook would put an
+      # authorization concern inside the domain declaration itself; this
+      # keeps it an application-boundary fact instead, the same shape
+      # `role`/`actor_id` already are. The tradeoff: a caller states what
+      # scope it is acting in, and `holds_role?` verifies a live grant
+      # exists for THAT scope — it does not independently confirm the
+      # scope matches whatever the command's own target data belongs to.
+      Current = Struct.new(:role, :actor_id, :as_of, :scope, keyword_init: true)
+
+      module_function
+
+      def current = Thread.current[:hecks_caller]
+
+      def as(role:, actor_id: nil, as_of: nil, scope: nil)
+        previous = Thread.current[:hecks_caller]
+        Thread.current[:hecks_caller] = Current.new(
+          role: role.to_s, actor_id: actor_id&.to_s, as_of: as_of, scope: scope&.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,135 @@
+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.
+        #
+        # `extra_identity_heads:` — EntityInterpreter's own callers only. An
+        # entity dispatch addresses not just the root aggregate but every
+        # entity ALONG THE CHAIN it walks to reach the piece the command
+        # actually belongs to (`Handler.Dispatch.Bind` is two hops), and each
+        # hop's own `identity_heads` is addressing the same way the root's
+        # are — `element_of` (entity_element.rb) reads them straight out of
+        # `args` to find the element, never as a fact the command itself
+        # declares. `[]` for a plain aggregate/port-operation dispatch, which
+        # has no chain to add.
+        def refuse_unknown_arguments(domain, aggregate, command, args, extra_identity_heads: [])
+          addressing = [:id, *aggregate.identity_heads, *extra_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