hecks 0.2.0 → 0.3.0

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

@@ -0,0 +1,181 @@
+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 related record's OWN fields, reachable by name from `given`/
+        # `ensures` — `customer.status`, `account.customer.status` — 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` is either the declaring aggregate/entity (its OWN
+        # `reference_to`, read off `source` — the record's stored state)
+        # or the command itself (a reference-typed ARGUMENT, read off
+        # `source` — the dispatch payload). Same shape either way: every
+        # reference-typed attribute `owner` declares becomes a key in the
+        # result, named by stripping the attribute's own `_id` suffix
+        # (`customer_id` → `customer`) — a no-op for an aliased reference
+        # that already carries no suffix (`reference_to Account, as:
+        # :source` → `source`), which is why this needs no separate case
+        # for `as:`.
+        #
+        # RECURSES into what it finds, so a chain like
+        # `account.customer.status` resolves in one pass: hydrating
+        # `account` also hydrates ITS OWN `customer_id` into a nested
+        # `customer` key. Depth-bounded rather than cycle-detected — nothing
+        # in this corpus dots more than two hops, 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,231 @@
+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
+          @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