hecks 0.2.0 → 1.0.0

data/lib/hecks/runtime/instance.rb

@@ -0,0 +1,175 @@
+require_relative "value"
+require_relative "identity"
+
+module Hecks
+  module Runtime
+    class Instance
+      attr_reader :aggregate, :id
+      attr_accessor :state
+      # OUT-OF-BAND ADAPTER BOOKKEEPING, NOT DOMAIN STATE — the optimistic-
+      # concurrency version a CAS-capable adapter (Postgres today) stamps
+      # on a record it reads/writes, so a later `save` can assert "commit
+      # only if nobody has written since". Deliberately absent from
+      # `to_h`/`[]`/`[]=`/`method_missing` : a domain author never declares
+      # this, a `given`/`ensures`/`invariant` can never read it, and no
+      # adapter that doesn't understand it (Memory, Heki) ever sets it —
+      # `nil` there just means "no CAS attempted", which is exactly what a
+      # plain `save` already does. See docs/decisions/ (concurrency-control
+      # ADR) for the full mechanism.
+      attr_accessor :version
+
+      # `args:` — THE ORIGINAL COMMAND PAYLOAD, offered only by a fresh
+      # creation (`CommandInterpreter#hydrate_legacy_creation`/
+      # `#hydrate_complete_state`/`#hydrate_prior_or_initial`, each already
+      # holding it when they mint a brand-new record). See
+      # `materialize_identity!` for why a composite identity needs it.
+      def initialize(aggregate:, id:, state: nil, args: nil)
+        @aggregate = aggregate
+        @id        = id
+        @state     = state ? self.class.hydrate_with_defaults(aggregate, state) : self.class.defaults(aggregate)
+        @version   = nil
+        materialize_identity!(args)
+      end
+
+      # Loading existing state runs the same default-fill a fresh instance
+      # gets: an attribute the record predates — a newly-required field
+      # with a declared default:, a list added since the record was
+      # written — arrives filled instead of nil. Only declared defaults
+      # fill in; an attribute with no default stays absent, exactly as
+      # stored.
+      def self.hydrate_with_defaults(aggregate, state)
+        hydrated = Value.hydrate(aggregate, state)
+        defaults(aggregate).each do |name, value|
+          hydrated[name] = value unless value.nil? || hydrated.key?(name)
+        end
+        hydrated
+      end
+
+      def self.defaults(aggregate)
+        state = aggregate.attributes.each_with_object({}) do |attr, acc|
+          # FROZEN, like a list that has had something appended to it.
+          # An untouched list is the easiest one to miss and the easiest
+          # to mutate: nothing has replaced it yet, so a caller pushing
+          # into it writes straight into the aggregate's own state.
+          acc[attr.name] = attr.list? ? Freezer.deep([]) : default_for(aggregate, attr)
+        end
+        state[aggregate.lifecycle.field.to_sym] = aggregate.lifecycle.default if aggregate.lifecycle
+        state
+      end
+
+      def self.default_for(aggregate, attribute)
+        return Value.for_attribute(aggregate, attribute, attribute.default) unless attribute.default.nil?
+        # An entity's members hydrate through the same path but an entity
+        # declares no value objects of its own — nothing to default-build.
+        return nil unless aggregate.respond_to?(:value_object)
+
+        value_object = aggregate.value_object(attribute.type)
+        return nil unless value_object && value_object.attributes.all? { |field| !field.default.nil? }
+
+        Value.build(value_object, {}, aggregate)
+      end
+
+      def [](name) = @state[name.to_sym]
+
+      def key?(name) = @state.key?(name.to_sym)
+
+      def []=(name, value)
+        @state[name.to_sym] = value
+      end
+
+      def method_missing(name, *args)
+        return @state[name] if @state.key?(name)
+
+        super
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        @state.key?(name) || super
+      end
+
+      # `id: @id` LAST, not first — see Facade::Handle#to_h's own comment
+      # for the full story (the same fix, landed there first): an
+      # aggregate free to declare its own attribute literally named `id`
+      # (BurningManPrep's `Item`, `attribute :id, ItemId`) has that
+      # attribute's own wrapped value object sitting in `@state[:id]` —
+      # merging `@state` on top of `{ id: @id }` let it silently clobber
+      # the correct bare identity. `@id` merged last always wins.
+      def to_h = @state.merge(id: @id)
+
+      # A COPY A MUTATION MAY TOUCH. Every adapter but Memory hands `find`
+      # a freshly-decoded Instance already; Memory's holds the record it
+      # eventually saves — the SAME state Hash, aliased. Before `ensures`
+      # existed, nothing could refuse between apply_mutations and save, so
+      # that aliasing was invisible: a dispatch either ran to completion or
+      # raised before touching state at all. `ensures` is the first refusal
+      # to sit AFTER mutation, and it found the bug the moment it did — an
+      # in-memory record left half-mutated by a dispatch that then refused.
+      # `command_interpreter`/`entity_interpreter` hydrate an EXISTING
+      # record through this, never through the adapter's own return value
+      # directly, so a refused ensures leaves the stored record untouched
+      # regardless of which adapter is holding it.
+      def dup
+        copy = super
+        copy.state = @state.dup
+        copy
+      end
+
+      def inspect
+        fields = @state.map { |k, v| "#{k}=#{v.inspect}" }.join(" ")
+        "#<#{@aggregate.hecks_name} #{@id} #{fields}>"
+      end
+
+      private
+
+      # M17 — a COMPOSITE identity (`identity_heads.size > 1`, e.g.
+      # `identified_by :branch_code, :box_number`) has no single
+      # `identified_by` to fall back to `:id` for — `@aggregate.identified_by`
+      # is nil the moment there is more than one head (`Behaviour::Identified
+      # #derive_identity`), so the single-head branch below never runs for
+      # it at all. A creating command that declares those heads as ordinary
+      # attributes but doesn't ALSO `sets` them (redundant with the identity
+      # the command's own args already named) used to persist every head as
+      # nil — the id correctly named the record, but the record's own
+      # attributes forgot what named it.
+      #
+      # Filled from `args`, never from splitting `@id` back apart — the
+      # same reason the single-head branch below won't guess a multi-path
+      # identifier from its joined string: `@id` is a display key, not a
+      # reversible serialization, and a composite's own separator can
+      # collide with a part's own text. `args` is only offered by a FRESH
+      # creation (`Instance.new`'s own `args:` comment); an existing record
+      # read back from storage has no args to lean on, and doesn't need
+      # one since a correctly-persisted record already carries its own
+      # heads.
+      def materialize_identity!(args = nil)
+        return materialize_composite_identity!(args) if @aggregate.identity_heads.size > 1
+
+        identity  = @aggregate.identified_by || :id
+        attribute = @aggregate.attribute(identity)
+        return unless attribute && @state[identity].nil?
+        # Several paths under one head mean the identifier is a display key,
+        # not a reversible serialization of the structured value object. A
+        # creating command supplies that object explicitly; persisted state
+        # hydrates it from storage. Never guess by splitting the joined id.
+        return if @aggregate.identity_heads.one? && @aggregate.identity_paths.size > 1
+
+        @state[identity] = Value.from_identifier(@aggregate, attribute, @id)
+      end
+
+      def materialize_composite_identity!(args)
+        return unless args
+
+        @aggregate.identity_paths.each do |path|
+          head = path.to_s.split(".").first.to_sym
+          attribute = @aggregate.attribute(head)
+          next unless attribute && @state[head].nil?
+
+          raw = Identity.from(@aggregate, args, path, value_owner: @aggregate)
+          next if raw.nil?
+
+          @state[head] = Value.from_identifier(@aggregate, attribute, raw)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/interpreting.rb

@@ -0,0 +1,90 @@
+require_relative "value"
+require_relative "aggregate_lock"
+
+module Hecks
+  module Runtime
+    # What every stepwise interpreter shares: the traced step, and the
+    # coercion of a command's declared arguments. Two copies of each lived
+    # in CommandInterpreter and EntityInterpreter, where they could only
+    # ever drift.
+    module Interpreting
+      # Each including interpreter gets its own `trace` — set by a spec to
+      # observe dispatch order (Vocabulary::AggregateDispatchOrder and
+      # Vocabulary::EntityDispatchOrder in language/bluebook/vocabulary.bluebook);
+      # nil in production, always — one array push and a nil check per step
+      # is the entire cost of leaving this in.
+      def self.included(interpreter)
+        interpreter.singleton_class.attr_accessor :trace
+      end
+
+      private
+
+      # Logged AFTER the step's own work, so a step that wraps sub-steps logs
+      # itself once everything inside it has already logged — trace order is
+      # completion order, which is dispatch order.
+      def step(name)
+        result = yield
+        self.class.trace << name if self.class.trace
+        result
+      end
+
+      # DRIVES `DISPATCH_ORDER` (CommandInterpreter/EntityInterpreter, each
+      # mirroring its own Vocabulary::*DispatchOrder — vocabulary.bluebook,
+      # held equal to it by spec/vocabulary_conformance_spec.rb) by `send`ing
+      # each declared step name against the including interpreter's own
+      # `step_<name>` handler, in declared order. What used to be `call`'s own
+      # literal sequence of method calls is now DATA driving that sequence —
+      # tracing a real dispatch and comparing it to the declaration is
+      # tautological once `call` mechanically follows the declaration; a
+      # conditional step (assign_creation_attributes, advance_lifecycle) still
+      # has to guard ITSELF at the top of its own handler and skip tracing
+      # when it does not fire, rather than the caller branching around it —
+      # see CommandInterpreter#step_assign_creation_attributes.
+      def run_dispatch_order(order, ctx)
+        order.each { |name| send(:"step_#{name}", ctx) }
+      end
+
+      # THE CONCURRENCY-CONTROL SPLIT — see docs/decisions/ (concurrency
+      # control ADR) for the full mechanism. A repository that declares
+      # `:optimistic_concurrency` (Postgres today) already closes the
+      # lost-update gap itself, via `step_save`'s CAS + `#call`'s own
+      # `StaleWrite` retry loop — an extra in-process lock here would be
+      # pointless overhead, not incorrect, so it's skipped for clarity.
+      # Every other repository (Heki, Memory — confirmed process-local
+      # data, never a second process writing the same store) gets a
+      # striped `Mutex` held for the WHOLE dispatch-order run, so a second
+      # thread's own hydrate can't start until the first thread's save has
+      # landed. `lock_key_id` is best-effort (`Identity.best_effort`) —
+      # `nil` still locks correctly, just coarser (by aggregate type).
+      def run_dispatch_order_with_isolation(order, ctx, lock_key_id:)
+        if ctx.repository.capabilities.include?(:optimistic_concurrency)
+          run_dispatch_order(order, ctx)
+        else
+          AggregateLock.for(ctx.domain, ctx.aggregate, lock_key_id).synchronize { run_dispatch_order(order, ctx) }
+        end
+      end
+
+      # Every declared attribute present in the payload passes the reference
+      # gate, then coercion — the same walk whether the command acts on an
+      # aggregate or on one of its entity's elements.
+      def coerce_declared_arguments(aggregate, command, args)
+        command.attributes.each_with_object(args.dup) do |attribute, normalized|
+          next unless normalized.key?(attribute.name)
+
+          Value.refuse_object_reference(command, attribute, normalized[attribute.name])
+          normalized[attribute.name] = Value.for_attribute(aggregate, attribute, normalized[attribute.name])
+        end
+      end
+
+      # Coercion only — CommandInterpreter's own refuse_unknown_arguments/
+      # refuse_absent_arguments are separate DISPATCH_ORDER steps now (the
+      # declared vocabulary lists all three as flat, sequential members, not
+      # one nesting the other two), and EntityInterpreter never had them here
+      # at all (an entity inherits its aggregate's own gate). One copy,
+      # shared, rather than the two identical ones that used to drift.
+      def normalize_args(aggregate, command, args)
+        coerce_declared_arguments(aggregate, command, args)
+      end
+    end
+  end
+end

data/lib/hecks/runtime/loader.rb

@@ -0,0 +1,184 @@
+require_relative "../facade/surface"
+require_relative "../ports/loading"
+require_relative "../ports/persistence"
+require_relative "dispatcher"
+require_relative "remote_dispatcher"
+require_relative "boot_gates"
+require_relative "registry"
+
+module Hecks
+  module Runtime
+    class Loader
+      # `install_facade:` defaults on — every ordinary caller wants
+      # `Widget::Item.Add(...)` sugar. A caller that only ever dispatches
+      # by FQN string (`SmokeTest`, the one caller so far) can pass
+      # `false` to skip it: `Facade::Surface.install` puts a bare global
+      # Ruby constant on `Object` per domain AND per aggregate name, with
+      # no scoping and no cleanup hook, so a tool booting arbitrary
+      # throwaway domains under generic names ("Widget", "Item", "Tag")
+      # would otherwise leak those names into the rest of the process —
+      # measured, not hypothetical: this exact leak once made an
+      # unrelated `dsl_spec.rb` example resolve a bare `Widget` constant
+      # to a stale smoke-test facade from a deleted temp directory instead
+      # of raising, corrupting that spec's own unrelated build. Skipping
+      # the install is safe because nothing downstream of a raw
+      # `Dispatcher` needs the sugar — `Dispatcher#dispatch`/`#query` work
+      # identically either way.
+      # `environment:` — see Adapters::Folder#load_domain's own comment
+      # for the mechanism. hecks never reads ENV itself (every other
+      # env-var lookup in this codebase lives in app-owned .world/
+      # .hecksagon files, never library internals) — a caller resolves
+      # its own env var name and passes the resulting string straight
+      # through, e.g. `Hecks.boot(path, environment:
+      # ENV.fetch("MYAPP_ENV", "development"))`.
+      def self.boot(path, shared: nil, install_facade: true, environment: nil)
+        loading   = Ports::Loading.bootstrap
+        directory = loading.bluebook_directory(path)
+        root      = loading.shared_root(shared, directory)
+        registry  = Registry.new(root: File.dirname(directory))
+
+        Hecks.with_registry(registry) do
+          loading.load_library
+          loading.load_project(root)
+          loading.load_domain(directory, environment: environment)
+        end
+
+        run_boot_gates!(registry, directory)
+        dispatcher = dispatcher_for(registry)
+        install_facade ? bind_runtime(dispatcher) : dispatcher
+      end
+
+      # THE EXPLICIT-FILE FORM — `paths` names the exact bluebook/hecksagon/
+      # world files to boot, in place, wherever they actually live. `boot`
+      # above only ever takes a directory and globs it; that is the right
+      # shape for a real deployment (`examples/banking`, a domain someone
+      # `cd`s into), and the wrong one for a caller that wants to declare a
+      # narrow, explicit scope and have it booted exactly as declared — a
+      # `.behaviors` file's own `loads` line is the motivating caller
+      # (`Hecks::Behaviors`), but this carries no behaviors-specific
+      # logic and is not gated behind requiring that module.
+      #
+      # NO COPYING, NO TEMP DIRECTORY. A prior port of this same idea
+      # (vendored into a downstream consumer, read before writing this)
+      # scoped a per-test boot by copying files into `Dir.mktmpdir` — which
+      # destroys real relative paths, and worse, makes a `persisted_by`
+      # path resolve against the TEMP copy's root instead of the project's
+      # own (confirmed there: a file adapter kept reading and writing the
+      # same deterministic tmp copy across an entire session, because
+      # `Hecks.boot`'s own `root` is always `File.dirname` of whatever
+      # directory it was handed). `directory` here is `File.dirname` of the
+      # FIRST real path in `paths` — genuinely on disk, not a copy — so
+      # every downstream path (`EraCheck`, `persisted_by`, `shared_root`)
+      # resolves exactly as an ordinary directory boot's would.
+      def self.boot_files(paths, shared: nil, install_facade: true, environment: nil)
+        loading   = Ports::Loading.bootstrap
+        files     = Array(paths).map { |path| File.expand_path(path) }
+        directory = File.dirname(files.first)
+        root      = loading.shared_root(shared, directory)
+        registry  = Registry.new(root: File.dirname(directory))
+
+        Hecks.with_registry(registry) do
+          loading.load_library
+          loading.load_project(root)
+          loading.load_selected(files, environment: environment)
+        end
+
+        run_boot_gates!(registry, directory)
+        dispatcher = dispatcher_for(registry)
+        install_facade ? bind_runtime(dispatcher) : dispatcher
+      end
+
+      # ADR 0031 — replaces two previously-hardcoded, unconditional calls
+      # with a per-boot `BootGates` instance holding exactly the gates THIS
+      # registry's own bound adapters have a capability for. Ordering is
+      # preserved: era-checking (when a persistence plugin contributes one)
+      # still runs before `verify!`, saga rehydration still runs after
+      # (conservative — see `SagaPersistence#rehydrate_sagas!`'s own
+      # comment).
+      #
+      # ADR 0033 — this loader no longer names `EraCheck`, or any other
+      # era-specific class, at all. Every LOADED persistence plugin
+      # (`Ports::Persistence.each_plugin` — nothing here if nothing was
+      # ever `require`d) is asked to contribute its own `:pre_verify`/
+      # `:post_verify` gates generically; `:saga_rehydration` is the one
+      # gate core still registers directly, because ADR 0031 already
+      # proved it's not era-specific.
+      def self.run_boot_gates!(registry, directory)
+        gates = BootGates.new
+        Ports::Persistence.each_plugin { |plugin| plugin.contribute_boot_gates(registry, gates) }
+        check_compute_rules_backstop!(registry)
+
+        gates.run!(:pre_verify, registry, directory)
+        registry.verify!
+
+        gates.register(:saga_rehydration, ->(reg, _dir) { reg.rehydrate_sagas! }, phase: :post_verify) if
+          registry.hecksagons.each_key.any? { |domain| registry.saga_persistence(domain) != Ports::Persistence::NULL_SAGA_STORE }
+        gates.run!(:post_verify, registry, directory)
+        gates
+      end
+
+      # The one piece of the old, era-owned `check_compute_rules!` core
+      # still carries — deliberately thinner. `registry.translations` is
+      # plain `Bluebook::Translation`/`TranslationAggregate`/
+      # `TranslationCompute`/`TranslationRekey` data (`bluebook/
+      # translation.rb`, core, no era-specific class involved), so this
+      # needs nothing plugin-specific to ask "does anything declare a
+      # compute/rekey rule at all." A LOADED persistence plugin (e.g. the
+      # era plugin's own `:era_compute_rules` gate, registered above) runs
+      # the real, adapter-aware version of this check and refuses by name
+      # ("...is bound to Memory") long before this ever would; this only
+      # fires when nothing did, because nothing was loaded to.
+      def self.check_compute_rules_backstop!(registry)
+        return if Ports::Persistence.plugins_loaded?
+
+        registry.translations.each do |translation|
+          translation.aggregates.each do |aggregate|
+            next if aggregate.computes.empty? && aggregate.rekeys.empty?
+
+            raise WiringError,
+                  "cannot boot #{translation.domain}::#{aggregate.name}: a compute/rekey rule is declared, but no " \
+                  "persistence plugin that can interpret it is loaded (e.g. require " \
+                  "\"hecks/ports/persistence/plugins/era\")"
+          end
+        end
+      end
+
+      # `RemoteDispatcher` for a domain routed through Lambda,
+      # `Dispatcher` otherwise — the ONE place this decision gets
+      # made, so everything built on top (`Handle`, `AggregateDoor`,
+      # `Facade::Surface`) never has to know which class it's holding.
+      # `registry.bluebooks.keys.first` is the just-booted domain's own
+      # name (insertion order — the target's own bluebook loads before
+      # any `uses_framework` chapter, `bin/project_rust`'s own header
+      # draws the identical distinction), not a directory basename.
+      #
+      # `dispatched_by("Lambda")` is its OWN, EXPLICIT verb — NOT
+      # inferred from `deployed_to("AwsLambda")`'s mere presence. Both
+      # Banking's and Embryonaut's `.world` files already declare
+      # `deployed_to("AwsLambda")` (it only means "a deploy target
+      # exists"), so treating that alone as "boot this domain against
+      # Lambda" would have silently rerouted Banking's every local
+      # boot — every spec, every `bin/console` session — the moment
+      # this landed. A domain opts in explicitly, the same way
+      # `persisted_by("PostgresEra")` is never inferred from anything
+      # else either.
+      def self.dispatcher_for(registry)
+        domain = registry.bluebooks.keys.first
+        settings = registry.world(domain)&.for_verb("dispatched_by") || {}
+        return Dispatcher.new(registry) unless settings[:adapter] == "Lambda"
+
+        RemoteDispatcher.new(registry, region: settings.fetch(:region, "us-east-1"))
+      end
+
+      # THE DOOR IS INSTALLED HERE, NOT STAMPED. This used to write the
+      # dispatcher onto every aggregate's class (`ruby_class.runtime =`) — the
+      # class-level global that made two boots in one process share one
+      # name. The facade's modules close over THIS dispatcher instead, so the
+      # binding lives in the surface a boot installs, not on anything shared.
+      def self.bind_runtime(dispatcher)
+        Facade::Surface.install(dispatcher)
+        dispatcher
+      end
+    end
+  end
+end