hecks 0.2.0 → 0.3.0

data/lib/hecks/runtime/entity_interpreter.rb

@@ -0,0 +1,228 @@
+require_relative "interpreting"
+require_relative "../naming"
+require_relative "../rendering"
+require_relative "errors"
+require_relative "identity"
+require_relative "instance"
+require_relative "value"
+require_relative "refusal_wording"
+require_relative "routing"
+require_relative "dependency_planning"
+require_relative "../ports/persistence/execution"
+require_relative "entity_element"
+
+module Hecks
+  module Runtime
+    class EntityInterpreter
+      include Interpreting
+
+      attr_reader :registry
+
+      # THE DECLARED ORDER, HAND-TYPED — mirrors Vocabulary::EntityDispatchOrder
+      # (language/bluebook/vocabulary.bluebook:217-232), held equal to it by
+      # spec/vocabulary_conformance_spec.rb the same way CommandInterpreter's
+      # own DISPATCH_ORDER is; see that constant's doc comment for why this is
+      # hand-typed rather than read live off the meta-domain at every dispatch.
+      # Shorter than the aggregate order for the same reasons the declaration
+      # itself gives : no refuse_unknown_arguments/refuse_absent_arguments (an
+      # entity inherits its aggregate's own gate) and no
+      # assign_creation_attributes (an entity is never created through this
+      # path).
+      DISPATCH_ORDER = Hecks::Vocabulary.symbols("EntityDispatchOrder")
+
+      # `instance` is the PARENT aggregate record (what gets saved and
+      # returned) ; `element`/`view` are the entity piece itself — `view`
+      # wraps `element` as it stood at `locate_element`, pre-mutation, and
+      # `enforce_ensures` builds its own settled wrapper off `element` as it
+      # stands after, the same split the original sequential code made.
+      #
+      # `chain` — S17, ADR 0026 — every entity the dotted verb passes
+      # through, root-first (`[Handler, Dispatch]` for `Handler.Dispatch.
+      # Bind`) ; `entity`/`entity_name` stay the CHAIN'S OWN LAST entry,
+      # the one a command actually belongs to and a mutation actually
+      # targets, so every step written before this ADR (enforce_givens,
+      # apply_mutations, advance_lifecycle, element_identity, ...) reads
+      # exactly as it always has. Only `locate_element` walks the chain.
+      Context = Struct.new(:domain, :aggregate, :entity, :entity_name, :command, :command_name,
+                           :args, :repository, :instance, :chain, :element, :view, :transition,
+                           :old_element, :result, :route, :plan, :persistence_outcome, :dry_run)
+
+      def initialize(registry, rules:)
+        @registry = registry
+        @rules    = rules
+      end
+
+      # `dry_run:` — CommandInterpreter#call's own twin, see that method's
+      # comment for the shared reasoning (Dispatcher#dry_run?'s own entry
+      # point). `step_save`/`step_emit` are the only two steps here that
+      # read it either.
+      def call(domain, aggregate, dotted, legacy_args, route: nil, with: nil, dry_run: false)
+        *entity_names, command_name = dotted.to_s.split(".")
+        if entity_names.empty?
+          raise UnknownVerb, RefusalWording.render("UnknownVerb", "entity_unknown",
+                                                   aggregate: aggregate.hecks_name, entity: dotted.to_s.inspect)
+        end
+
+        chain  = walk_entity_chain(aggregate, entity_names)
+        entity = chain.last
+        command = entity.command(command_name) ||
+                  raise(UnknownVerb, RefusalWording.render("UnknownVerb", "entity_no_command",
+                                                           entity: entity.hecks_name, command: command_name.inspect))
+
+        args = Routing.payload(command, with: with, legacy: legacy_args)
+        ctx = Context.new(domain, aggregate, entity, entity_names.join("."), command, command_name, args)
+        ctx.chain = chain
+        ctx.route = route
+        ctx.dry_run = dry_run
+        ctx.plan = DependencyPlanning::Analyzer.call(aggregate: entity, command: command)
+        run_dispatch_order(DISPATCH_ORDER, ctx)
+        [ctx.instance, ctx.result, ctx.plan, ctx.persistence_outcome]
+      end
+
+      private
+
+      # ONE HOP PER DOTTED SEGMENT — `ProcessManager.Handler.Dispatch.Bind`
+      # (once the dispatcher has already stripped "Domain::Aggregate.")
+      # walks Handler off the aggregate, then Dispatch off Handler, each
+      # step reading `.entities` exactly the way the single-level case
+      # always did — a nested entity is "structurally interchangeable
+      # with an aggregate" (Entity's own header) for precisely this
+      # reason. Two levels is what Handler/Dispatch need today ; nothing
+      # here assumes it stops at two.
+      def walk_entity_chain(aggregate, entity_names)
+        owner = aggregate
+        entity_names.map do |name|
+          found = owner.entities.find { |piece| piece.hecks_name == name } ||
+                  raise(UnknownVerb, RefusalWording.render("UnknownVerb", "entity_unknown",
+                                                           aggregate: owner.hecks_name, entity: name.inspect))
+          owner = found
+          found
+        end
+      end
+
+      def step_normalize_args(ctx)
+        ctx.args = step(:normalize_args) { normalize_args(ctx.aggregate, ctx.command, ctx.args) }
+      end
+
+      def step_refuse_role_mismatch(ctx)
+        step(:refuse_role_mismatch) { @rules.refuse_role_mismatch(ctx.command, ctx.domain) }
+      end
+
+      def step_resolve_references(ctx)
+        step(:resolve_references) { @rules.resolve_references(ctx.domain, ctx.command, ctx.args) }
+      end
+
+      def step_hydrate_parent(ctx)
+        ctx.repository = @registry.repository(ctx.domain, ctx.aggregate)
+        ctx.instance = step(:hydrate_parent) {
+          parent(ctx.repository, ctx.aggregate, ctx.entity_name, ctx.command_name, ctx.args, ctx.route)
+        }
+      end
+
+      def step_locate_element(ctx)
+        ctx.element = step(:locate_element) {
+          EntityElement.locate_chain(ctx.aggregate, ctx.chain, ctx.instance, ctx.args, ctx.command_name, ctx.route)
+        }
+        # `view` was hydrated ONCE, here, into its OWN state hash
+        # (Value.hydrate builds a fresh Hash — never aliased with `element`)
+        # — exactly right for enforce_givens, which must read pre-mutation.
+        ctx.view = Instance.new(aggregate: ctx.entity, id: EntityElement.element_identity(ctx.entity, ctx.element).to_s,
+                                state: ctx.element)
+      end
+
+      def step_enforce_givens(ctx)
+        step(:enforce_givens) {
+          @rules.enforce_givens(ctx.view, ctx.command, ctx.args, domain: ctx.domain, declaring: ctx.entity, parent: ctx.instance)
+        }
+      end
+
+      def step_admissible_transition(ctx)
+        ctx.transition = step(:admissible_transition) { @rules.admissible_transition(ctx.entity, ctx.command, ctx.view) }
+      end
+
+      def step_apply_mutations(ctx)
+        ctx.old_element = ctx.element.dup unless ctx.command.ensures.empty?
+        step(:apply_mutations) {
+          ctx.command.mutations.each { |mutation|
+            EntityElement.apply_to_element(@rules, ctx.aggregate, ctx.entity, ctx.element, mutation, ctx.args)
+          }
+        }
+      end
+
+      def step_advance_lifecycle(ctx)
+        return unless ctx.transition
+
+        step(:advance_lifecycle) { ctx.element[ctx.entity.lifecycle.field] = ctx.transition.target }
+      end
+
+      # An ensures reads the SETTLED record, so it needs a view hydrated from
+      # `element` as it stands now, mutations included — unlike `view` above,
+      # built once and read pre-mutation by enforce_givens.
+      def step_enforce_ensures(ctx)
+        step(:enforce_ensures) do
+          settled = Instance.new(aggregate: ctx.entity, id: ctx.view.id, state: ctx.element)
+          @rules.enforce_ensures(settled, ctx.command, ctx.args, old: ctx.old_element, domain: ctx.domain, parent: ctx.instance)
+        end
+      end
+
+      # THE PARENT AGGREGATE's own invariants — `ctx.instance` is the
+      # parent record an entity mutation writes into (this file's own
+      # `Context` comment), the SAME boundary an aggregate-level
+      # invariant guards regardless of which interpreter changed it. No
+      # separate "entity invariant" exists (S10, ADR 0025 scopes
+      # `invariant` to the aggregate only) — see `Admissibility#
+      # enforce_invariants`'s own comment.
+      def step_enforce_invariants(ctx)
+        step(:enforce_invariants) { @rules.enforce_invariants(ctx.instance, ctx.aggregate, domain: ctx.domain) }
+      end
+
+      # `dry_run:` skips this — see CommandInterpreter#step_save's own
+      # comment, same reasoning and the same precedent
+      # (`step_assign_creation_attributes`'s own conditional-skip).
+      def step_save(ctx)
+        return if ctx.dry_run
+
+        step(:save) do
+          @rules.resolve_state_references(ctx.domain, ctx.aggregate, ctx.instance.state)
+          ctx.repository.save(ctx.instance)
+          ctx.persistence_outcome = Ports::Persistence::Outcome.new(status: :saved, instance: ctx.instance)
+        end
+      end
+
+      # `dry_run:` skips this too — nothing was committed, so `ctx.result`
+      # stays nil and `Dispatcher#dry_run?` never reads it.
+      def step_emit(ctx)
+        return if ctx.dry_run
+
+        ctx.result = step(:emit) { @rules.emit(ctx.command, ctx.domain, ctx.aggregate, ctx.instance, ctx.args, ctx.repository) }
+      end
+
+      # THE PARENT AGGREGATE, addressed exactly as `CommandInterpreter#hydrate`
+      # addresses one acting on itself — derive from the declared identity first
+      # (`Identity.of`), and let a bare `id:` name an already-derived record when
+      # the identity itself is not what the caller is holding.
+      def parent(repository, aggregate, entity_name, command_name, args, route = nil)
+        parent_id = route&.aggregate ||
+                    Identity.of(aggregate, args) ||
+                    Identity.from(aggregate, args, :id) ||
+                    raise(NotFound, RefusalWording.render("NotFound", "entity_parent_no_identity",
+                                                          command: command_name, aggregate: aggregate.hecks_name,
+                                                          entity: entity_name, identity: Identity.reading(aggregate)))
+        found = repository.find(parent_id) ||
+                raise(NotFound, RefusalWording.render("NotFound", "record_missing",
+                                                      aggregate: aggregate.hecks_name,
+                                                      identity:  Identity.reading(aggregate),
+                                                      offered:   Rendering.describe(parent_id)))
+        found.dup
+      end
+
+      # `locate_chain`/`element_of`/`element_identity`/`apply_to_element` and
+      # their own helpers used to live here — moved to `Runtime::EntityElement`
+      # (see that file's own header) so `CommandInterpreter`'s own
+      # `delegate_to_entity` step can locate and mutate the same element the
+      # same way, against an aggregate record already held in memory. `call`,
+      # above, and every `step_*` method reach them through that module now;
+      # nothing about the STEPS themselves changed.
+    end
+  end
+end

data/lib/hecks/runtime/era_check.rb

@@ -0,0 +1,136 @@
+require_relative "../ports/persistence"
+require_relative "../ports/persistence/binding_policy"
+require_relative "../ports/persistence/lineage"
+require_relative "../naming"
+require_relative "../framework"
+require_relative "registry"
+
+module Hecks
+  module Runtime
+    # The boot-time era gate, run for the adapters that HAVE eras — the
+    # lineage-capable ones. An era is a fact about stored data that some
+    # adapter can carry across a shape change; an adapter that cannot
+    # translate has no era to hold, and holding one for it would record
+    # history about data nothing can act on.
+    #
+    # The whole domain is handed to the capable adapter's own era check
+    # (Postgres: hold, recognize, mint, or refuse toward the scaffold),
+    # which keeps its era facts as rows BESIDE its data. That
+    # co-location is load-bearing — a watermark only means something
+    # against the journal it was cut from, and an approval recorded
+    # anywhere but the reviewed database binds to nothing.
+    #
+    # The capability is asked of the adapter, never of its name: a
+    # second adapter that grows an era story declares lineage_capable?
+    # and era_check! and needs no change here.
+    #
+    # Detection and identity are separate jobs: this check never hashes
+    # anything — era names come from the store, already minted (by the
+    # scaffold) or absent. Refusal wordings are contract, pinned by the
+    # corpus.
+    module EraCheck
+      module_function
+
+      # EACH BLUEBOOK'S OWN SOURCE, not one file read once and reused
+      # for every bluebook in the registry — true as long as a domain
+      # directory only ever held exactly one, and silently wrong the
+      # moment `uses_framework` made a second, differently-sourced
+      # bluebook (Governance, Identity — `lib/hecks/framework/bluebook/`,
+      # not the domain's own directory) share a boot with the first.
+      # Caught the hard way: three domains booted together, one real
+      # source text (the domain's own), and every OTHER domain's era-1
+      # held THAT text under its own name — a shadow-parse of it later
+      # reconstructs a completely different shape, and every boot after
+      # the first refuses toward a scaffold that was never the real
+      # drift.
+      def check!(registry, directory)
+        registry.bluebooks.each_value do |bluebook|
+          check_bluebook!(registry, bluebook, source_text_for(bluebook, directory), directory: directory)
+        end
+      end
+
+      # The domain's own directory first, matched by name — a real app's
+      # directory may hold more than one file once `uses_framework`
+      # exists, so ".first" alone can no longer be trusted, the exact
+      # way it silently wasn't the day this was found: three domains
+      # booted together, one real source text read once (the domain's
+      # own, ".first"'d), and every OTHER domain's era-1 held THAT text
+      # under its own name — a later shadow-parse of it reconstructs a
+      # completely different shape, and every boot after the first
+      # refuses toward a scaffold that was never the real drift.
+      #
+      # A single-file directory whose one file names something ELSE
+      # falls back to it anyway (a fixture may legitimately name its
+      # file differently from the `Hecks.bluebook` it declares) — UNLESS
+      # this bluebook is a known framework member, in which case that
+      # one file is certainly some OTHER domain's, not this one's, and
+      # the framework registry is asked instead — the only other place a
+      # bluebook in this registry could have come from, per
+      # `uses_framework`.
+      def source_text_for(bluebook, directory)
+        domain_files = Dir[File.join(directory, "*.bluebook")]
+        own = domain_files.select do |path|
+          File.foreach(path, encoding: "UTF-8").any? { |line| line.match?(/\A\s*Hecks\.bluebook\s+#{Regexp.escape(bluebook.name.inspect)}/) }
+        end
+        own = domain_files if own.empty? && domain_files.size == 1 && !Framework.members.key?(bluebook.name)
+        own = [Framework.members[bluebook.name]].compact if own.empty?
+        return if own.empty?
+
+        own.map { |path| File.read(path, encoding: "UTF-8") }.join("\n")
+      end
+
+      def check_bluebook!(registry, bluebook, current_text, directory: nil)
+        check_compute_rules!(registry, bluebook)
+
+        first = bluebook.aggregates.first
+        return unless first
+
+        adapter_name = adapter_for(registry, bluebook.name, first)
+        return unless lineage_capable?(registry, adapter_name)
+
+        unless current_text
+          raise WiringError,
+                "cannot boot #{bluebook.name}: bound to a lineage-capable adapter, but no source file for " \
+                "it could be found (checked #{directory.inspect} and the framework registry)"
+        end
+
+        settings = registry.world(bluebook.name)&.for_binding(Ports::Persistence::VERB, adapter_name) || {}
+        registry.adapter_class(adapter_name).era_check!(
+          registry: registry, bluebook: bluebook, current_text: current_text, settings: settings,
+          directory: directory
+        )
+      end
+
+      # The per-rule capability gate — NOT an era fact, and so it
+      # survives on every adapter: a compute rule's SQL is its only
+      # implementation, so an aggregate carrying one cannot boot
+      # anywhere but Postgres, whatever any shape comparison would say.
+      def check_compute_rules!(registry, bluebook)
+        bluebook.aggregates.each do |aggregate|
+          lineage = Ports::Persistence::Lineage.for(registry, bluebook.name, aggregate)
+          next unless lineage&.computes?
+
+          adapter = adapter_for(registry, bluebook.name, aggregate)
+          next if lineage_capable?(registry, adapter)
+
+          raise WiringError, "compute rules require the Postgres adapter; #{aggregate.name} is bound to #{adapter}"
+        end
+      end
+
+      def adapter_for(registry, domain, aggregate)
+        Ports::Persistence::BindingPolicy.resolve(registry, domain, aggregate).adapter
+      end
+
+      # The capability idiom: an adapter CLASS that answers
+      # lineage_capable? with true carries eras and may act on drift
+      # (translate, fork, merge). Postgres alone does today; the seam is
+      # what lets a second one arrive without touching this file.
+      def lineage_capable?(registry, adapter_name)
+        adapter_class = registry.adapters[adapter_name] && registry.adapter_class(adapter_name)
+        adapter_class.respond_to?(:lineage_capable?) && adapter_class.lineage_capable?
+      rescue StandardError
+        false
+      end
+    end
+  end
+end

data/lib/hecks/runtime/era_guard/shape_diff.rb

@@ -0,0 +1,128 @@
+module Hecks
+  module Runtime
+    module EraGuard
+      # The pure half: computing an aggregate's structural signature and
+      # diffing two eras' shapes. No file I/O — everything here answers
+      # from the IR it is handed, which is why the Postgres mint path can
+      # call it too.
+      module ShapeDiff
+        def shape(aggregate)
+          aggregate.attributes.map { |attribute|
+            [attribute.name, attribute_signature(aggregate, attribute.type)]
+          }.sort_by(&:first)
+        end
+
+        # A plain type name for a primitive; `[type_name, member_signatures]`
+        # for a value object or entity, walked recursively — so two
+        # attributes with the same declared type name but a different
+        # internal shape are never mistaken for unchanged.
+        def attribute_signature(aggregate, type_name, seen = [])
+          container = nested_type(aggregate, type_name)
+          return type_name if container.nil? || seen.include?(type_name)
+
+          members = container.attributes.map { |member|
+            [member.name, attribute_signature(aggregate, member.type, seen + [type_name])]
+          }.sort_by(&:first)
+          [type_name, members]
+        end
+
+        def nested_type(aggregate, type_name)
+          aggregate.value_object(type_name) || aggregate.entities.find { |entity| entity.name == type_name }
+        end
+
+        # Attributes present now that the held shape never had — the
+        # addition side of drift, which `uncovered_attributes` above never
+        # looks at, since it only walks the HELD shape (vanish/retype).
+        # Most additions are free (ADR 0025, "Added attributes and
+        # absence"): a default:, a list_of (frozen []), or a value object
+        # whose fields all default fill an existing record automatically
+        # via `Instance.hydrate_with_defaults`. Only the fourth case — a
+        # non-optional attribute with no way to fill itself — can leave an
+        # existing record with the field genuinely absent, and that is
+        # what this reports: unfilled by a declared translation's own
+        # `backfill`, OR by a move/convert that lands an OLD field inside
+        # this brand-new attribute (`Lineage#fills?` — the destination-
+        # side question, never `explains?`'s source-side one, since a
+        # rename from Crate to Bin can introduce a top-level attribute
+        # name that never existed to have "vanished").
+        def unsafe_additions(aggregate, held_aggregate, lineage)
+          held_names = held_aggregate.attributes.map(&:name)
+
+          aggregate.attributes
+                   .reject { |attribute| held_names.include?(attribute.name) }
+                   .select { |attribute| possibly_absent?(aggregate, attribute) }
+                   .reject { |attribute| lineage&.fills?(attribute.name.to_s) }
+                   .map(&:name)
+        end
+
+        # THE FOUR-ROW TABLE, as a predicate over the fourth row only — the
+        # other three (default:, list_of, a fully-defaulted value object)
+        # all fill an existing record for free and never reach here.
+        def possibly_absent?(aggregate, attribute)
+          return false if attribute.optional?
+          return false unless attribute.default.nil?
+          return false if attribute.list?
+
+          value_object = aggregate.value_object(attribute.type)
+          return false if value_object && value_object.attributes.all? { |field| !field.default.nil? }
+
+          true
+        end
+
+        # Paths the translation needs to explain: attributes that vanished
+        # by name, attributes that kept their name but changed type (a
+        # `convert` is what lets that be declared at all), and — recursing
+        # into a same-named, same-typed value object — its OWN members
+        # vanishing or changing type one level down, reported as a dotted
+        # path ("price.currency"). A pure addition, at any depth, never
+        # needs covering; only vanish-or-retype does, matching the
+        # top-level rule at every depth.
+        def uncovered_attributes(aggregate, held_aggregate, lineage)
+          paths = held_aggregate.attributes.flat_map do |held_attribute|
+            current_attribute = aggregate.attribute(held_attribute.name)
+            next [held_attribute.name.to_s] unless current_attribute
+
+            diff_type(held_attribute.name.to_s, held_attribute.type, current_attribute.type, held_aggregate, aggregate, lineage)
+          end
+
+          return paths unless lineage
+
+          paths.reject { |path| lineage.explains?(path) }
+        end
+
+        # `held_type`/`current_type` are type NAMES, resolved against each
+        # side's OWN value_object AND entity declarations — neither is ever
+        # nested in the DSL, only in the type graph, so both are always
+        # looked up flat off their respective aggregate. A `list_of` entity
+        # is only reached here to DETECT a member vanish-or-retype; there is
+        # no per-element translation machinery yet (`move`/`convert`/`drop`
+        # only reach into a single nested hash, not each element of an
+        # array) — the only way to satisfy a refusal on an entity path
+        # today is a top-level `drop` of the whole list attribute, which
+        # `explains?` already recognizes as covering everything nested
+        # under it. Blunt, but loud beats silent.
+        def diff_type(path, held_type, current_type, held_aggregate, aggregate, lineage, seen = [])
+          if held_type != current_type
+            # A declared retype says the two TYPE names mean the same shape
+            # — accept the pair, but still recurse into the members so a
+            # member drift hiding beneath the rename is caught by name.
+            return [path] unless lineage&.retype?(held_type, current_type)
+          end
+          return [] if seen.include?(current_type)
+
+          held_container = nested_type(held_aggregate, held_type)
+          current_container = nested_type(aggregate, current_type)
+          return [] unless held_container && current_container
+
+          held_container.attributes.flat_map do |held_member|
+            current_member = current_container.attribute(held_member.name)
+            next ["#{path}.#{held_member.name}"] unless current_member
+
+            diff_type("#{path}.#{held_member.name}", held_member.type, current_member.type, held_aggregate, aggregate, lineage,
+                      seen + [current_type])
+          end
+        end
+      end
+    end
+  end
+end