hecks 0.2.0 → 1.0.0

data/lib/hecks/runtime/value.rb

@@ -0,0 +1,125 @@
+require "json"
+require_relative "../rendering"
+require_relative "value/invariant_violation"
+require_relative "value/coercion"
+require_relative "value/admission"
+
+module Hecks
+  module Runtime
+    # A typed value object in hand: frozen fields, read by name. How one is
+    # MADE — coerced from a raw argument, checked against its declared
+    # numeric types, patterns and closed sets — is the class-side engine in
+    # value/coercion.rb and value/admission.rb, extended here so the door
+    # stays where it always was: `Value.for`, `Value.build`.
+    class Value
+      extend Coercion
+      extend Admission
+
+      attr_reader :value_object
+
+      # FROZEN THROUGH, not just on top.
+      #
+      # `@fields.freeze` alone stops a key being added or removed and
+      # nothing else: the String, Array or Hash a field HOLDS stays
+      # mutable, so `vo[:value] << "!"` edits a value object in place —
+      # demonstrated on a real dispatch before this was written, not
+      # supposed. Same shape as the three freezing bugs already fixed
+      # (list attributes, the event log, query rows), where the container
+      # was frozen and the contents were not.
+      #
+      # A value object is the one thing in the domain that has no
+      # identity to change over — `with` already answers a NEW one rather
+      # than mutating — so freezing it through is what it always claimed
+      # to be.
+      def initialize(value_object, fields)
+        @value_object = value_object
+        @fields       = Freezer.deep(fields.transform_keys(&:to_sym))
+        freeze
+      end
+
+      def type_name = @value_object.hecks_name
+      def [](field) = @fields[field.to_sym]
+      def key?(field) = @fields.key?(field.to_sym)
+      def to_h = @fields.transform_values { |value| self.class.materialize(value) }
+      def to_json(*) = JSON.generate(to_h)
+
+      def ==(other)
+        other.is_a?(self.class) && other.type_name == type_name && other.to_h == to_h
+      end
+
+      def with(field, value)
+        self.class.build(@value_object, @fields.merge(field.to_sym => value))
+      end
+
+      def self.materialize(value)
+        case value
+        when self then value.to_h
+        when Array then value.map { |item| materialize(item) }
+        when Hash then value.transform_values { |item| materialize(item) }
+        else value
+        end
+      end
+
+      # `materialize`, but a single-attribute value object (`sole_attribute`
+      # — [[feedback_name_the_scalar_field]]) recurses into its own bare
+      # field instead of building `{field: ...}` — a Board's own `label`
+      # unwraps to `"Kanban"`, not `{value: "Kanban"}`. NOT a replacement
+      # for `materialize` itself: every existing report/query/command
+      # caller keeps the wrapped shape it already depends on (Banking's
+      # own `CustomerPortfolio` reads `payment[:amount][:cents]`, and
+      # changing that out from under it would be a real breaking change,
+      # not a bug fix). This is read_model_interpreter.rb's own opt-in,
+      # used ONLY for a `group_by`-declared head's own rows — grouping
+      # needs a real scalar to key by regardless, so a report already
+      # asking for that gets the unwrap for free.
+      def self.materialize_unwrapped(value)
+        case value
+        when self
+          sole = value.value_object.sole_attribute
+          return materialize_unwrapped(value[sole.name]) if sole
+
+          # NOT `value.to_h` — `Value#to_h` materializes each field through
+          # plain `materialize`, so a VO nested inside a multi-attribute VO
+          # would already be a plain Hash by the time this method ever saw
+          # it, and never reach the `when self` branch above. Read each
+          # field straight off `value` instead, so recursion actually
+          # happens through THIS method the whole way down.
+          value.value_object.attributes.to_h { |attr| [attr.name, materialize_unwrapped(value[attr.name])] }
+        when Array then value.map { |item| materialize_unwrapped(item) }
+        when Hash then value.transform_values { |item| materialize_unwrapped(item) }
+        else value
+        end
+      end
+
+      # REDUCES AN APPEND-ONLY SUB-LOG TO ITS CURRENT STATE — the same
+      # "a later fact supersedes an earlier one" reduction this runtime
+      # already performs replaying an AGGREGATE's own command history
+      # into its current attributes, applied here to a single `list_of`
+      # FIELD acting as its own miniature append-only log (a placement
+      # history, a tombstone-style soft-delete list, a versioned
+      # setting). `rows` is what a `list_of` attribute hands back — an
+      # Array of `Value`, in append order — and `key` names the field
+      # that identifies "the same logical thing" across entries.
+      #
+      # GROUPING ONLY, NEVER INTERPRETATION. What counts as "removed,"
+      # how to order what survives — that meaning belongs to whichever
+      # domain declared the field, never here: a generic reduction that
+      # started guessing domain semantics would need to keep guessing
+      # forever, once per shape of "gone" any caller ever invents. The
+      # caller filters and sorts the result; this only groups it.
+      def self.latest_by(rows, key)
+        rows.each_with_object({}) { |row, latest| latest[row.public_send(key)] = row }.values
+      end
+
+      def method_missing(name, *args)
+        return @fields[name] if @fields.key?(name)
+
+        super
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        @fields.key?(name) || super
+      end
+    end
+  end
+end

data/lib/hecks/runtime.rb

@@ -0,0 +1,107 @@
+# Hecks::Runtime
+#
+# The runtime layer's face. `lib/hecks/runtime/` held thirteen files and
+# no parent, so the layer had no surface of its own : `lib/hecks.rb`
+# required each file by hand, and the runtime's own state — the registry a
+# declaration is being collected into — sat on the top-level Hecks module
+# beside the DSL words.
+#
+# What lives here is what RUNS a domain :
+#
+#   Runtime.boot(path)          load a directory and return its Dispatcher
+#   Runtime.with_registry(r)    bind the ambient registry for the duration of a load
+#   Runtime.current_registry    the registry a declaration is landing in, or nil
+#
+# What does NOT live here is what DECLARES one — `Hecks.bluebook`,
+# `.hecksagon`, `.port`, `.adapter`, `.world` are loading words and stay on the
+# top-level module, which now reads as a facade over this.
+#
+#   runtime = Hecks::Runtime.boot("examples/pizzas/bluebook")
+#   runtime.dispatch("Pizzas::Pizza.CreatePizza", name: "Margherita")
+#
+# NOTE, and it is the reason this file exists : `current_registry` is still
+# process-global. Each boot builds a fresh Registry, and `Loader.bind_runtime`
+# installs a fresh facade door whose modules close over THAT boot's dispatcher
+# — no class-level runtime binding remains, so two boots in one process no
+# longer share dispatch state, only the top-level NAME (the last-bound door
+# wins the constant, which is what per-boot install means). Owning the state
+# here was the first move ; the dispatcher reachable per-runtime rather than
+# through a constant was the second, and it is done — the door is the only
+# constant left, and it is a projection, not the runtime.
+
+require_relative "runtime/event"
+require_relative "runtime/value"
+require_relative "runtime/identity"
+require_relative "runtime/instance"
+require_relative "runtime/registry"
+require_relative "runtime/capability_graph"
+require_relative "runtime/errors"
+require_relative "runtime/refusal_wording"
+require_relative "runtime/caller"
+require_relative "runtime/routing"
+require_relative "runtime/command_rules"
+require_relative "runtime/dependency_planning"
+require_relative "runtime/command_interpreter"
+require_relative "runtime/port_operation_interpreter"
+require_relative "runtime/entity_interpreter"
+require_relative "runtime/query_interpreter"
+require_relative "runtime/read_model_interpreter"
+require_relative "runtime/policy_interpreter"
+require_relative "runtime/saga_interpreter"
+require_relative "runtime/dispatcher"
+require_relative "runtime/rebuild_sweep"
+require_relative "runtime/tenant_check"
+require_relative "runtime/loader"
+
+module Hecks
+  module Runtime
+    class << self
+      # The registry declarations are currently landing in, or nil outside a
+      # boot. Read by the DSL collectors on the top-level module and by the
+      # extraction port.
+      attr_reader :current_registry
+
+      # Load a bluebook directory and return the Dispatcher bound to it.
+      # `install_facade:`, `environment:` — see Loader.boot.
+      def boot(path, shared: nil, install_facade: true, environment: nil)
+        Loader.boot(path, shared: shared, install_facade: install_facade, environment: environment)
+      end
+
+      # `paths` form — see Loader.boot_files.
+      def boot_files(paths, shared: nil, install_facade: true, environment: nil)
+        Loader.boot_files(paths, shared: shared, install_facade: install_facade, environment: environment)
+      end
+
+      # Bind the ambient registry for the duration of the block, restoring
+      # whatever was there before. Nesting is safe ; a raise still restores.
+      def with_registry(registry)
+        previous          = @current_registry
+        @current_registry = registry
+        yield
+      ensure
+        @current_registry = previous
+      end
+
+      # Bind the ambient caller (see Runtime::Caller) for the duration of
+      # the block — who a command's declared `role`, if any, is checked
+      # against.
+      #
+      # `as_of:` is OPTIONAL, same opt-in shape as `actor_id:` — a caller
+      # that wants a Governance `RoleAssignment`'s `starts_at` enforced
+      # passes `as_of: Ports::Clock.now(registry)` here, at the door,
+      # exactly where `cli_runner.rb` already merges `Clock.now` into a
+      # command's own args. Nothing on the dispatch path calls the clock
+      # itself — see `Ports::Clock`'s own header for why — so an unbound
+      # `as_of` leaves `starts_at` unchecked, exactly as before.
+      #
+      # `scope:` is OPTIONAL too — a caller that states which scope it is
+      # acting in gets that scope checked against the matching
+      # `RoleAssignment`'s own `scope`, not just its `role_name`. See
+      # `Runtime::Caller::Current`'s own header for why this lives here
+      # rather than as a command-level DSL construct.
+      def as_caller(role:, actor_id: nil, as_of: nil, scope: nil, &block)
+        Caller.as(role: role, actor_id: actor_id, as_of: as_of, scope: scope, &block)
+      end
+    end
+  end
+end