hecks 0.2.0 → 1.0.0

data/lib/hecks/runtime/command_rules/authorization.rb

@@ -0,0 +1,65 @@
+require_relative "../caller"
+require_relative "../errors"
+require_relative "../refusal_wording"
+require_relative "../../ports/authorization"
+
+module Hecks
+  module Runtime
+    class CommandRules
+      # Whether the caller may run this command at all — a `role` mismatch,
+      # the one check that runs before any domain-state work, alongside the
+      # argument gate rather than after it.
+      #
+      # TWO CHECKS, NOT A REPLACEMENT — ADR 0025 §9's own caution against
+      # "silently downgrading `role` to documentation" cuts both ways: a
+      # caller who never named WHO they are (every caller before this) is
+      # checked exactly the way it always has been, string equality
+      # against the command's own `role`. Only a caller that ALSO binds an
+      # `actor_id` (`Hecks.as_caller(role:, actor_id:)`) reaches the
+      # real check — a live Governance::RoleAssignment lookup through
+      # `Ports::Authorization`, once the command's domain declares
+      # `uses_framework "Governance"` (`HecksagonBuilder` refuses any
+      # domain that declares a `role` and does not, at build time — see
+      # its own `refuse_ungoverned_roles!`). An identified caller is never
+      # let back through the string fallback: a real identity that holds
+      # no matching grant is refused, not waved through because it also
+      # happens to type the right word.
+      module Authorization
+        # OPT-IN, on BOTH sides. No caller bound: unchecked, exactly as
+        # today. No role declared: unchecked too — `role` is genuinely
+        # optional in this language (roughly a third of banking's own
+        # commands declare none), so a command that never named a role has
+        # nothing to check a caller against.
+        def refuse_role_mismatch(command, domain)
+          caller = Caller.current
+          return unless caller
+          return if command.role.to_s.empty?
+
+          authorized =
+            if caller.actor_id && governance_attached?(domain)
+              Ports::Authorization.holds_role?(registry, actor_id: caller.actor_id, role: command.role,
+                                                          as_of: caller.as_of, scope: caller.scope)
+            else
+              caller.role == command.role
+            end
+
+          return if authorized
+
+          raise Unauthorized, RefusalWording.render("Unauthorized", "role_mismatch",
+                                                    command: command.hecks_name, role: command.role,
+                                                    caller_role: caller.role)
+        end
+
+        private
+
+        # SELF-EXEMPT, like `HecksagonBuilder#refuse_ungoverned_roles!` —
+        # Governance IS the thing a `holds_role?` lookup runs against, so
+        # its own commands are always checked by the string fallback, not
+        # a lookup against itself.
+        def governance_attached?(domain)
+          domain.to_s == "Governance" || registry.hecksagon(domain)&.framework_members&.include?("Governance") || false
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/command_rules/emission.rb

@@ -0,0 +1,34 @@
+require_relative "../event"
+
+module Hecks
+  module Runtime
+    class CommandRules
+      # What a command's `emits` becomes: an Event in the registry's log,
+      # and — where the store can hold one — a recorded event beside the
+      # data it describes.
+      module Emission
+        # `correlation` arrives HERE rather than being merged onto the
+        # event afterwards. It is part of the transaction — known from
+        # `dispatch`'s own argument before anything is emitted — and an
+        # event that is still being written to is not yet a record of
+        # what happened. Setting it at construction is what lets the
+        # event be frozen the moment it exists.
+        def emit(command, domain, aggregate, instance, args, repository, correlation = nil)
+          command.emits.map do |event_name|
+            event = Event.new(
+              name:        event_name,
+              aggregate:   "#{domain}::#{aggregate.hecks_name}",
+              id:          instance.id,
+              payload:     args,
+              occurred_at: Time.now.utc.iso8601,
+              correlation: correlation
+            )
+            @registry.event_log << event.emit!
+            repository.record_event(event) if repository.respond_to?(:record_event)
+            event
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/command_rules/references.rb

@@ -0,0 +1,189 @@
+require_relative "../errors"
+require_relative "../refusal_wording"
+require_relative "../value"
+
+module Hecks
+  module Runtime
+    class CommandRules
+      # A reference must point at something that EXISTS.
+      #
+      # `reference_to Customer` is the one guarantee an aggregate reference is
+      # for, and it was declared 14 times across banking and enforced nowhere :
+      # an Account could belong to a customer who was never registered, and
+      # every gate stayed green because
+      # no corpus step ever passed a dangling reference.
+      module References
+        # Resolved here rather than in coercion because coercion is pure — it
+        # holds no repository. A reference INTO ANOTHER DOMAIN is left alone : a
+        # cross-domain target may legitimately not be loaded, which is the same
+        # reading `across` policies already get.
+        #
+        # Shared by CommandInterpreter and EntityInterpreter — an entity command
+        # can declare a reference-typed attribute the same way an aggregate
+        # command can, even though nothing in the real corpus does yet.
+        def resolve_references(domain, command, args)
+          command.attributes.each do |attribute|
+            next unless attribute.reference?
+            next unless args.key?(attribute.name)
+
+            held = args[attribute.name]
+            next if held.nil?
+
+            target = referenced_aggregate(attribute)
+            next unless target
+
+            validate_reference_values(domain, target, held, list: attribute.list?)
+          end
+        end
+
+        # Structural references are checked again against the settled state.
+        # This is what makes a `has_many` declared on an aggregate honest even
+        # when a command supplies its list through an ordinary typed argument.
+        def resolve_state_references(domain, construct, state)
+          construct.attributes.each do |attribute|
+            next unless attribute.reference?
+
+            held = state[attribute.name]
+            validate_relationship_cardinality(construct, attribute, held)
+            next if held.nil?
+
+            target = referenced_aggregate(attribute)
+            next unless target
+
+            validate_reference_values(domain, target, held, list: attribute.list?)
+          end
+
+          Array(construct.entities).each do |entity|
+            field = construct.attribute(Naming.snake(entity.hecks_name).to_sym) ||
+                    construct.attributes.find { |attribute| attribute.type.to_s == entity.hecks_name.to_s }
+            next unless field
+
+            Array(state[field.name]).each { |row| resolve_state_references(domain, entity, row) }
+          end
+        end
+
+        # `has_one` and `belongs_to` mean exactly one target unless the
+        # declaration explicitly says optional. State validation owns this
+        # boundary because a command may leave an aggregate field untouched;
+        # checking only command arguments would let a required relationship be
+        # persisted as nil. `has_many` admits zero members, so its empty list is
+        # already a valid cardinality and needs no presence refusal.
+        def validate_relationship_cardinality(construct, attribute, held)
+          return if attribute.relationship.nil? || attribute.list?
+          return unless held.nil? && !attribute.optional?
+
+          raise TypeMismatch,
+                "#{construct.hecks_name}.#{attribute.name} is a required " \
+                "#{attribute.relationship} relationship — expected one " \
+                "#{attribute.type.target_name} identity, got nil"
+        end
+
+        # The reference RESOLVES itself — through the chapter's own IR, so the
+        # bluebook's declared heads are the index. This used to regex the target's
+        # name out of "Reference<Customer>" and then search
+        # `registry.bluebook(domain).aggregates` for it — and later reached the
+        # target through Ruby's constant tree, a class thrown away for its `.ir`
+        # the moment it was found.
+        def referenced_aggregate(attribute)
+          attribute.type.resolve
+        end
+
+        def validate_reference_values(domain, target, held, list:)
+          values = list ? Array(held) : [held]
+          values.each do |value|
+            key = reference_key(value)
+            next if key.empty?
+            next if @registry.repository(domain, target).find(key)
+
+            raise NotFound,
+                  RefusalWording.render("NotFound", "reference_target_missing",
+                                        target: target.name, heads: target.identity_heads.join(", "),
+                                        key: key.inspect)
+          end
+        end
+
+        # `value` is the referenced record's own id, EXACTLY as `Identity.of`
+        # would build it for that record — a bare scalar for a single-field
+        # identity (the overwhelming common case; Banking's own plain
+        # `reference_to Customer` holds one already, so `Value.
+        # materialize_unwrapped` is a no-op passthrough here), or a
+        # `Naming.identity`-joined string for a compound one
+        # (`belongs_to Translation, as: :translation_ref` — Translation's
+        # own `identified_by :domain, :from, :to`, THREE fields). Before
+        # this, plain `value.to_s` on that compound case's own coerced
+        # Value hit Ruby's default `Object#to_s` (a raw, run-to-run-random
+        # memory address) instead of joining the record's real id — found
+        # live via bin/fuzz on the self-hosted "translation" domain
+        # (replay_is_deterministic), the SAME class of gap `Identity.from`
+        # already had for a compound `identified_by`'s own bare (undotted)
+        # attribute paths. `materialize_unwrapped` recurses a multi-
+        # attribute value object to a plain Hash keyed by attribute name,
+        # in declaration order — `Naming.identity` on `.values` reproduces
+        # the identical join `Identity.of` itself would produce for the
+        # SAME fields.
+        def reference_key(value)
+          unwrapped = Value.materialize_unwrapped(value)
+          return Naming.identity(unwrapped.values).to_s if unwrapped.is_a?(Hash)
+
+          unwrapped.to_s
+        end
+
+        # A COMMAND ARGUMENT's own related record, reachable by name from
+        # `given`/`ensures` — `disputed_by.status`, say, `CardPayment
+        # .Dispute`'s own fresh `Reference<Customer>` argument — without
+        # teaching the pure expression evaluator anything about
+        # repositories. The lookup happens HERE, once, before evaluation;
+        # `Resolver#lookup` just digs into a plain Hash exactly as it
+        # always has.
+        #
+        # `owner` NARROWED TO `command` ONLY (S12, ADR 0025 — "rules
+        # confined to their own aggregate boundary"): dereferencing the
+        # DECLARING aggregate/entity's own STORED `reference_to` used to
+        # be the other half of this method's job — a live query against
+        # another aggregate's own repository, every time a `given`/
+        # `ensures`/`invariant` ran. That half is gone; a cross-aggregate
+        # fact a rule needs now has to be a `projects`-maintained LOCAL
+        # field (`AggregateBuilder#projects_impl`'s own comment), already
+        # present in `subject`'s own state, no hydration needed. A
+        # reference-typed COMMAND ARGUMENT stays in bounds, though — the
+        # ADR's own boundary list names "its command arguments" as
+        # readable, and nothing is stored yet for a fresh argument to
+        # project from; resolving it once here, synchronous with THIS
+        # command's own admission, is a different shape from a live query
+        # against an ALREADY-PERSISTED reference. `enforce_givens`/
+        # `enforce_ensures` are this method's only two remaining callers,
+        # both passing `command`/`args`, never a `subject`'s own
+        # aggregate — verified before this comment was written, not
+        # assumed.
+        #
+        # RECURSES into what it finds, so a chain deeper than one hop
+        # still resolves in one pass. Depth-bounded rather than cycle-
+        # detected — nothing in this corpus dots more than two hops on a
+        # fresh argument, and a bound is simpler than tracking visited
+        # (type, id) pairs for a cycle nothing here declares.
+        DEREFERENCE_DEPTH = 4
+        private_constant :DEREFERENCE_DEPTH
+
+        def dereference(domain, owner, source, depth: DEREFERENCE_DEPTH)
+          return {} if depth <= 0 || owner.nil?
+
+          owner.attributes.each_with_object({}) do |attribute, hydrated|
+            next unless attribute.reference?
+
+            id = source[attribute.name]
+            next if id.nil?
+
+            target = referenced_aggregate(attribute)
+            next unless target
+
+            record = @registry.repository(domain, target).find(id.to_s)
+            next unless record
+
+            name = attribute.name.to_s.sub(/_id\z/, "").to_sym
+            hydrated[name] = record.state.merge(dereference(domain, target, record.state, depth: depth - 1))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/command_rules.rb

@@ -0,0 +1,28 @@
+require_relative "command_rules/admissibility"
+require_relative "command_rules/references"
+require_relative "command_rules/arithmetic"
+require_relative "command_rules/emission"
+require_relative "command_rules/authorization"
+
+module Hecks
+  module Runtime
+    # The rules both interpreters consult, one concern per file beside
+    # this one: whether a command may run (admissibility), whether its
+    # references point at anything (references), what its arithmetic
+    # mutations mean (arithmetic), what its emits become (emission), and
+    # whether the caller may run it at all (authorization).
+    class CommandRules
+      include Admissibility
+      include References
+      include Arithmetic
+      include Emission
+      include Authorization
+
+      attr_reader :registry
+
+      def initialize(registry)
+        @registry = registry
+      end
+    end
+  end
+end

data/lib/hecks/runtime/dependency_planning.rb

@@ -0,0 +1,245 @@
+require_relative "../bluebook/expression"
+
+module Hecks
+  module Runtime
+    # Persistence-neutral facts derived from a command's existing semantic IR.
+    # This module deliberately does not execute a plan or choose a repository.
+    module DependencyPlanning
+      ATOMIC_PUT = :atomic_put
+      TRANSACTIONAL_FALLBACK = :load_apply_validate_store
+
+      Plan = Struct.new(
+        :read_set,
+        :write_set,
+        :payload_read_set,
+        :complete_state,
+        :state_independent,
+        :unresolved_dependencies,
+        keyword_init: true
+      ) do
+        def complete_state? = complete_state
+        def state_independent? = state_independent
+
+        # Capability negotiation is correctness-first: an optimization is
+        # selected only when both the semantic proof and adapter capability
+        # are present. This is planning data only; no runtime path calls it yet.
+        def strategy_for(capabilities: [])
+          return TRANSACTIONAL_FALLBACK unless complete_state? && state_independent?
+          return TRANSACTIONAL_FALLBACK unless capabilities.map(&:to_sym).include?(ATOMIC_PUT)
+
+          ATOMIC_PUT
+        end
+      end
+
+      module ExpressionReads
+        module_function
+
+        # Read the same parsed canonical-expression nodes the evaluator uses.
+        # A generic Struct walk keeps this additive when the expression grammar
+        # gains a composed node; only Lookup nodes carry domain dependencies.
+        def paths(canonical)
+          collect(Bluebook::Expression::Evaluator.parse(canonical), Set.new)
+        end
+
+        def collect(node, bound_names)
+          case node
+          when Bluebook::Expression::Resolver::Lookup
+            root = node.path.to_s.split(".", 2).first
+            bound_names.include?(root) ? [] : [node.path.to_s]
+          when Bluebook::Expression::Resolver::BlockPredicate
+            collect(node.receiver, bound_names) +
+              collect(node.predicate, bound_names | [node.param.to_s])
+          when Struct
+            node.each_pair.flat_map { |_name, value| collect(value, bound_names) }
+          when Array
+            node.flat_map { |value| collect(value, bound_names) }
+          else
+            []
+          end
+        end
+      end
+
+      class Analyzer
+        STATEFUL_MUTATIONS = %i[append increment decrement multiply clamp remove].freeze
+
+        def self.call(aggregate:, command:) = new(aggregate, command).call
+
+        def initialize(aggregate, command)
+          @aggregate = aggregate
+          @command = command
+          @owner_fields = aggregate.attributes.to_set(&:name)
+          @owner_fields << aggregate.lifecycle.field.to_sym if aggregate.lifecycle
+          # `projects` FIELDS (S12, ADR 0025) ARE OWNER STATE TOO — a
+          # `given`/`ensures` reading one (e.g. `customer_status ==
+          # "active"`) is reading this record's own stored field, same
+          # as any attribute, even though nothing here WRITES it via a
+          # declared mutation (`CommandInterpreter#seed_projected_fields`
+          # populates it outside this analysis entirely). Left out of
+          # `known_writes` deliberately: `add_preservation_reads` then
+          # correctly treats it as a prior-state read that must survive
+          # a partial mutation, which is exactly right — a projected
+          # field's freshness comes from the interpreter reseeding it on
+          # save, not from anything a caller-supplied write set carries.
+          if aggregate.respond_to?(:projected_fields)
+            aggregate.projected_fields.each { |field| @owner_fields << field.name }
+          end
+          @payload_fields = command.attributes.to_set(&:name)
+          @state_reads = Set.new
+          @payload_reads = Set.new
+          @writes = Set.new
+          @known_writes = Set.new
+          @unresolved = Set.new
+        end
+
+        def call
+          analyze_initial_state
+          analyze_mutations
+          analyze_lifecycle
+          analyze_rules(command.givens, phase: :before)
+          analyze_rules(command.ensures, phase: :after)
+          analyze_rules(aggregate.invariants, phase: :after)
+          add_preservation_reads
+
+          complete = unresolved.empty? && owner_fields.subset?(known_writes)
+          independent = complete && state_reads.empty?
+
+          Plan.new(
+            read_set:                sorted(state_reads),
+            write_set:               sorted(writes),
+            payload_read_set:        sorted(payload_reads),
+            complete_state:          complete,
+            state_independent:       independent,
+            unresolved_dependencies: unresolved.to_a.sort.freeze
+          ).freeze
+        end
+
+        private
+
+        attr_reader :aggregate, :command, :owner_fields, :payload_fields,
+                    :state_reads, :payload_reads, :writes, :known_writes, :unresolved
+
+        # A fresh Instance supplies these values without reading a stored
+        # record. Keep this aligned with Instance.defaults/default_for. They
+        # establish completeness but are not command mutations, so they do not
+        # appear in write_set.
+        def analyze_initial_state
+          aggregate.attributes.each do |attribute|
+            known_writes << attribute.name if deterministic_initial_value?(attribute)
+          end
+
+          known_writes << aggregate.lifecycle.field.to_sym if aggregate.lifecycle
+        end
+
+        def deterministic_initial_value?(attribute)
+          return true if attribute.list? || attribute.optional? || !attribute.default.nil?
+          return false unless aggregate.respond_to?(:value_object)
+
+          value_object = aggregate.value_object(attribute.type)
+          value_object&.attributes&.all? { |field| !field.default.nil? }
+        end
+
+        def analyze_mutations
+          command.mutations.each do |mutation|
+            target = mutation.target.to_sym
+            writes << target
+
+            unless owner_fields.include?(target)
+              unresolved << "mutation target #{target} is not an aggregate field"
+              next
+            end
+
+            if mutation.op == :set
+              known_writes << target if analyze_source?(mutation.source)
+            elsif STATEFUL_MUTATIONS.include?(mutation.op)
+              state_reads << target
+              analyze_source?(mutation.source)
+            else
+              unresolved << "mutation operation #{mutation.op} has no dependency rule"
+            end
+          end
+        end
+
+        # Returns true only when the source is known without prior aggregate
+        # state. Hash sources are the canonical append binding shape.
+        def analyze_source?(source)
+          case source
+          when Symbol
+            if payload_fields.include?(source)
+              payload_reads << source
+              return true
+            end
+            if owner_fields.include?(source)
+              state_reads << source
+              return false
+            end
+
+            unresolved << "mutation source #{source} has no payload or aggregate field"
+            false
+          when Hash
+            source.values.map { |value| analyze_source?(value) }.all?
+          else
+            true
+          end
+        end
+
+        def analyze_lifecycle
+          lifecycle = aggregate.lifecycle
+          return unless lifecycle
+
+          if command.from
+            state_reads << lifecycle.field
+          end
+
+          return if lifecycle.transitions_for(command.hecks_name).empty?
+
+          writes << lifecycle.field
+          known_writes << lifecycle.field
+        end
+
+        def analyze_rules(rules, phase:)
+          rules.each do |rule|
+            ExpressionReads.paths(rule.canonical).each { |path| classify_path(path, phase) }
+          rescue ArgumentError => error
+            unresolved << "expression #{rule.canonical.inspect} could not be analyzed: #{error.message}"
+          end
+        end
+
+        def classify_path(path, phase)
+          head, nested = path.split(".", 2)
+          name = head.to_sym
+
+          if name == :parent
+            parent_field = nested.to_s.split(".", 2).first
+            if parent_field.empty? || !owner_fields.include?(parent_field.to_sym)
+              unresolved << "#{path} does not name parent aggregate state"
+            else
+              state_reads << parent_field.to_sym
+            end
+          elsif name == :old
+            old_field = nested.to_s.split(".", 2).first
+            if old_field.empty? || !owner_fields.include?(old_field.to_sym)
+              unresolved << "#{path} does not name prior aggregate state"
+            else
+              state_reads << old_field.to_sym
+            end
+          elsif payload_fields.include?(name)
+            payload_reads << name
+          elsif owner_fields.include?(name)
+            state_reads << name if phase == :before || !known_writes.include?(name)
+          else
+            unresolved << "expression path #{path} has no payload or aggregate field"
+          end
+        end
+
+        # A partial mutation must preserve every untouched field on the
+        # correctness path. Those prior values are real reads even when no rule
+        # names them. A deterministic write needs no preservation read.
+        def add_preservation_reads
+          state_reads.merge(owner_fields - known_writes)
+        end
+
+        def sorted(values) = values.to_a.sort.freeze
+      end
+    end
+  end
+end