hecks 0.2.0 → 1.0.0

data/lib/hecks/facade/surface/aggregate_door.rb

@@ -0,0 +1,185 @@
+require_relative "../../bluebook/dsl/hecksagon_builder"
+require_relative "../../bluebook/dsl/domain_port_builder"
+require_relative "../../bluebook/dsl/const_shim"
+require_relative "../../bluebook/hexagon"
+require_relative "../handle"
+require_relative "../../naming"
+
+module Hecks
+  module Facade
+    module Surface
+      # One aggregate's door: creating verbs as module methods returning
+      # the record in hand, CRUD delegation to the repository, the
+      # `persisted_by`-style binding collector a `.hecksagon` lands on, and
+      # the aggregate-scoped `port` a `.hecksagon` lands on beside it.
+      module AggregateDoor
+        def aggregate_module(dispatcher, domain, ir)
+          fqn  = "#{domain}::#{ir.hecks_name}"
+          door = Module.new
+
+          ir.attributes.each do |attribute|
+            next unless RESERVED.include?(attribute.name.to_sym)
+
+            warn "[hecks] #{ir.hecks_name}##{attribute.name} shadows a built-in — no reader defined"
+          end
+
+          # A creating verb is a MODULE method returning the new record in hand ;
+          # a verb that reaches an existing record lives on the Handle. `!` —
+          # a command DOES something (mutates, may refuse), Ruby's own
+          # convention for that ; `Naming.snake` alone used to leave a
+          # creating command's bare name claiming the exact spelling a
+          # QUERY of the SAME business name also wants (`Account`'s own
+          # "Open" — the creating command AND a query listing open
+          # accounts, a real same-aggregate collision this corpus already
+          # has) — the suffix is what makes both nameable at all, not
+          # merely a style choice.
+          ir.commands.select(&:creates?).each do |command|
+            door.define_singleton_method("#{Naming.snake(command.hecks_name)}!") do |**args|
+              Handle.new(dispatcher: dispatcher, domain: domain, ir: ir,
+                         instance: dispatcher.dispatch("#{fqn}.#{command.hecks_name}", with: args).instance)
+            end
+          end
+
+          # A query is a MODULE method too — same level as a creating
+          # command, since neither needs an existing record in hand — but
+          # bare: a query reads and returns, nothing to warn a caller
+          # about the way `!` does for a command. Answers the raw row
+          # array `dispatcher.query` itself answers, the same shape
+          # `runtime.query("#{fqn}.Name")` already gave.
+          ir.queries.each do |query|
+            door.define_singleton_method(Naming.snake(query.hecks_name)) do |**args|
+              dispatcher.query("#{fqn}.#{query.hecks_name}", **args)
+            end
+          end
+
+          door.define_singleton_method(:fqn)        { fqn }
+          door.define_singleton_method(:ir)         { ir }
+
+          # THE SAME VERB THE CHAPTER ANSWERS, one level down. Every
+          # construct emits its own IR (Hecks::IR), so an aggregate
+          # is a legitimate thing to project — `Pizzas::Order.project(
+          # Projections::IR)` is this aggregate's IR, not the chapter's.
+          #
+          # A chapter-scoped target refuses here rather than inventing an
+          # answer: `Projector.admits!` is what tells `Projections::IR`
+          # (`from: :any`) apart from `Projections::Shape`
+          # (`from: :chapter`), which used to return a confidently empty
+          # `{"aggregates" => []}` for an aggregate.
+          door.define_singleton_method(:project) do |target, out: nil, **options|
+            key      = Projector.key_for(target)
+            artifact = Projector.call(key, bluebook: ir, options: options)
+            return artifact unless out
+
+            Projector.write(artifact, out, as: Projector.emits_for(key))
+          end
+          door.define_singleton_method(:repository) { dispatcher.registry.repository(domain, ir) }
+          door.define_singleton_method(:commands)   { ir.commands.map { |c| "#{Naming.snake(c.hecks_name)}!" }.sort }
+          door.define_singleton_method(:queries)    { ir.queries.map { |q| Naming.snake(q.hecks_name) }.sort }
+          # ONE AGGREGATE'S USAGE DOCUMENT — the same projection the chapter
+          # answers with, narrowed to this head. `commands` above already
+          # answers "what can I call"; this answers "and what does each one
+          # want, refuse, and guarantee", which is the rest of the question.
+          door.define_singleton_method(:docs) do |**options|
+            Projector.call(:docs, bluebook: dispatcher.registry.bluebook(domain),
+                                  options:  options.merge(aggregate: ir.hecks_name))
+          end
+          # ONE AGGREGATE, READ BACK IN ENGLISH — the same narrowing `:docs`
+          # takes, aimed at `:narrate` instead.
+          door.define_singleton_method(:narrate) do |**options|
+            Projector.call(:narrate, bluebook: dispatcher.registry.bluebook(domain),
+                                     options:  options.merge(aggregate: ir.hecks_name))
+          end
+          door.define_singleton_method(:count)      { dispatcher.registry.repository(domain, ir).count }
+          door.define_singleton_method(:events)     { dispatcher.events.select { |event| event.aggregate == fqn } }
+
+          door.define_singleton_method(:find) do |id|
+            found = dispatcher.registry.repository(domain, ir).find(id)
+            found && Handle.new(dispatcher: dispatcher, domain: domain, ir: ir, instance: found)
+          end
+
+          door.define_singleton_method(:all) do |**opts|
+            dispatcher.registry.repository(domain, ir).all(**opts).map do |instance|
+              Handle.new(dispatcher: dispatcher, domain: domain, ir: ir, instance: instance)
+            end
+          end
+
+          # THE SAME REASON `method_missing` BELOW EXISTS AT ALL — a facade
+          # left over from a PREVIOUS boot in this process shadows the fresh
+          # `BindingProxy` a `.hecksagon` would otherwise reach through
+          # `ConstShim`/`const_missing`, so `Pizzas::Pizza.port(...)` lands
+          # HERE instead once any boot has run before.
+          #
+          # RE-RESOLVED, NOT THE CLOSED-OVER `ir` — this door can be a STALE
+          # one, built by a boot from earlier in this same process, sitting
+          # on the `Pizzas`/`Pizza` constants only because nothing has
+          # re-installed them since. Attaching to this door's OWN `ir` would
+          # attach the port to a discarded aggregate from that old boot,
+          # invisible to the CURRENT one actually being loaded — silently,
+          # the exact way `method_missing` below already has to avoid it for
+          # a plain bind, via `HecksagonBuilder.collector` rather than
+          # anything this door closes over. `Hecks.current_registry` is
+          # the same "whichever boot is actually in progress" indirection,
+          # and `BindingProxy#port` already re-resolves through it the same
+          # way — this is that door's fallback twin, not a shortcut past it.
+          door.define_singleton_method(:port) do |name, &block|
+            current = Hecks.current_registry&.bluebook(domain)&.aggregate(ir.hecks_name) or
+              raise Bluebook::DSL::Malformed, "#{fqn}.port(#{name.inspect}) called outside a boot"
+
+            domain_port = Bluebook::DSL::ConstShim.with(->(const) { const }) do
+              Bluebook::DSL::DomainPortBuilder.build(name, owner: current.hecks_name, &block)
+            end
+            domain_port.operations.each do |operation|
+              operation.attributes.select(&:reference?).each { |attribute| attribute.type.declared_in = current }
+            end
+            current.add_port(domain_port)
+            self
+          end
+
+          door.define_singleton_method(:method_missing) do |verb, *args, **kwargs, &block|
+            collector = Bluebook::DSL::HecksagonBuilder.collector
+            return super(verb, *args, **kwargs, &block) unless collector
+
+            collector << Bluebook::Bind.new(
+              aggregate: fqn,
+              verb:      verb.to_s,
+              adapter:   args.first.to_s,
+              role:      kwargs[:role]&.to_s
+            )
+            block&.call
+            self
+          end
+
+          door.define_singleton_method(:respond_to_missing?) do |name, include_private = false|
+            !Bluebook::DSL::HecksagonBuilder.collector.nil? || super(name, include_private)
+          end
+
+          # THE SAME STALE-FACADE HAZARD `method_missing`/`port` ABOVE ALREADY
+          # DOCUMENT, one door lower — `Surface.install` installs an aggregate's
+          # OWN name as a bare TOP-LEVEL constant too (`Namespace.install(Object,
+          # aggregate.hecks_name, ...)`, surface.rb's own `install`), not only
+          # nested under its chapter. So once ANY domain has booted once in this
+          # process, `Account::Debit` written while declaring some OTHER
+          # bluebook — same domain or a different one — reaches THIS door's
+          # const_missing directly, never `Object.const_missing`/`ConstShim::
+          # Hook` at all: real modules resolve without ever calling that.
+          #
+          # `ir.hecks_name`, NOT the qualified `fqn` — a scoped reference has to
+          # read the SAME either way, whether or not a stale door happens to be
+          # sitting on this process from an earlier boot; qualifying it here
+          # would make `Account::Debit`'s own meaning depend on incidental
+          # process history, which is the exact instability S0b exists to
+          # remove (docs/dsl-work-slices.md — "two domains in one registry" is
+          # this file's own reason for being owned by that slice).
+          door.define_singleton_method(:const_missing) do |name|
+            resolver = Bluebook::DSL::ConstShim.resolver
+            return resolver.call("#{ir.hecks_name}::#{name}") if resolver
+
+            super(name)
+          end
+
+          door
+        end
+      end
+    end
+  end
+end

data/lib/hecks/facade/surface/chapter.rb

@@ -0,0 +1,107 @@
+require_relative "../../bluebook/dsl/binding_proxy"
+require_relative "../../bluebook/dsl/const_shim"
+require_relative "../../bluebook/dsl/hecksagon_builder"
+
+module Hecks
+  module Facade
+    module Surface
+      # One chapter's module: vision and aggregate roll-call on the
+      # singleton, one aggregate door per declared head, and the
+      # declaration hook for names the door does not carry.
+      module Chapter
+        def chapter_module(dispatcher, bluebook)
+          chapter = Module.new
+          chapter.define_singleton_method(:vision)     { bluebook.vision }
+          chapter.define_singleton_method(:aggregates) { bluebook.aggregates.map(&:name).sort }
+
+          # THE CHAPTER, EXPLAINING ITSELF. `Projector::DocsProjector` reads
+          # nothing but this bluebook's own IR, so the document cannot drift
+          # from the domain — the same guarantee `bin/reference` gives the DSL
+          # reference by generating it from the Syntax chapter.
+          #
+          # A METHOD RATHER THAN ONLY A SCRIPT because that is what gets it
+          # read: `QualityControl.docs` in a console, beside `vision` and
+          # `aggregates`, at the moment somebody is wondering what a verb
+          # wants. Projected on each call rather than memoised — it is a pure
+          # read of the IR, and a stale document is the entire thing this
+          # exists to prevent.
+          chapter.define_singleton_method(:docs) do |**options|
+            Projector.call(:docs, bluebook: bluebook, options: options)
+          end
+
+          # THE CHAPTER, READ BACK IN ENGLISH — `Projector::NarrateProjector`
+          # beside `:docs`, for the reader who needs to confirm the domain is
+          # right rather than call it: `QualityControl.narrate` in a console.
+          chapter.define_singleton_method(:narrate) do |**options|
+            Projector.call(:narrate, bluebook: bluebook, options: options)
+          end
+
+          # THE DOMAIN'S OWN IR, PROJECTED. `Projector` has taken
+          # `call(name, bluebook:, options:)` since §30, but nothing could
+          # reach it from a booted domain — this module already closes
+          # over the one `Bluebook` every projector wants and simply
+          # never handed it out, so every bin/ projector rebuilt a
+          # Registry and reloaded the files to recover what was already
+          # sitting here.
+          #
+          #   Pizzas.project(Projections::OIDC)
+          #   Pizzas.project(Projections::Shape, out: "shape.json")
+          #
+          # No `to_ir` companion: `project(Projections::IR)` already
+          # answers with the canonical serialized form, and handing out
+          # the live graph as well would be a second way to say the same
+          # thing. Anything genuinely needing the graph is a projector,
+          # and a projector is given it.
+          #
+          # `out:` writes and everything else is passed through to the
+          # target — so `options` stays the projector's own vocabulary
+          # (`audience:` for OIDC) rather than a fixed set this method
+          # would have to know about.
+          chapter.define_singleton_method(:project) do |target, out: nil, **options|
+            key      = Projector.key_for(target)
+            artifact = Projector.call(key, bluebook: bluebook, options: options)
+            return artifact unless out
+
+            Projector.write(artifact, out, as: Projector.emits_for(key))
+          end
+
+          bluebook.aggregates.each do |aggregate|
+            chapter.const_set(aggregate.hecks_name, aggregate_module(dispatcher, bluebook.name, aggregate))
+          end
+
+          # INSIDE A HECKSAGON, A NAME IS A DECLARATION, NOT A LOOKUP. A
+          # `.hecksagon` may name an aggregate this door does not carry — a STALE
+          # door from an earlier boot resolving another registry's chapter, the
+          # exact hazard the constant tree used to hide by reinstalling on every
+          # load. With a collector open, the name becomes a `BindingProxy`
+          # recording the same bind the aggregate module would ; without one, it
+          # is a genuine NameError, exactly as before.
+          #
+          # THE OTHER READER OF A MISS is S0b's own bridge (docs/dsl-work-
+          # slices.md, const_shim.rb's `ScopedConstant`): a bluebook still being
+          # DECLARED that names `#{bluebook.name}::Something` — an event, a
+          # command reference, an `admits:` — reaches HERE, not
+          # `Object.const_missing`, the moment this chapter's own facade already
+          # exists (a previous boot in the same process, or this same chapter
+          # re-entering its own name). `ConstShim.active?` is exactly as true
+          # here as it is at the top level, mid-declaration, and consulting the
+          # SAME resolver is what makes a scoped reference resolve identically
+          # whether or not a facade happens to be built yet — the earlier
+          # attempt's own failure mode (this file's own history) was a bridge
+          # that worked only BEFORE any facade existed.
+          chapter.define_singleton_method(:const_missing) do |name|
+            collector = Bluebook::DSL::HecksagonBuilder.collector
+            return Bluebook::DSL::BindingProxy.new("#{bluebook.name}::#{name}", collector) if collector
+
+            resolver = Bluebook::DSL::ConstShim.resolver
+            return resolver.call("#{bluebook.name}::#{name}") if resolver
+
+            super(name)
+          end
+
+          chapter
+        end
+      end
+    end
+  end
+end

data/lib/hecks/facade/surface.rb

@@ -0,0 +1,48 @@
+require_relative "surface/chapter"
+require_relative "surface/aggregate_door"
+
+module Hecks
+  module Facade
+    # THE DOOR, WITHOUT THE CLASSES.
+    #
+    # `Pizzas::Pizza.create_pizza(...)` is the public surface (HANDOVER rule 3),
+    # and this is what serves it now : anonymous per-boot modules whose
+    # singleton methods close over the dispatcher and dispatch by FQN — the
+    # same shape `Router::NamespaceInstaller` proved. Nothing here is a domain
+    # class ; the IR is the only graph, and the door is a projection of it,
+    # installed by `Loader.bind_runtime` and re-installed whole on the next
+    # boot. How a chapter's module is built is surface/chapter.rb; how one
+    # aggregate's door is built is surface/aggregate_door.rb.
+    #
+    # The hexagon-binding door rides along : `Pizzas::Pizza.persisted_by("Heki")`
+    # in a `.hecksagon` file lands on the module's `method_missing`, which
+    # records an `Bind` into whatever `HecksagonBuilder.collector` is open
+    # AT CALL TIME — so even a facade left over from a previous boot records
+    # into the current builder, and a chapter with no constant at all falls
+    # through to `ConstShim` → `BindingProxy`, which mints byte-identical binds.
+    module Surface
+      # These would shadow the machinery a Handle runs on, so a field named one
+      # of them gets no reader and says so — the same warning the class door gave.
+      RESERVED = %i[id state events reload inspect to_h hash class].freeze
+
+      extend Chapter
+      extend AggregateDoor
+
+      module_function
+
+      def install(dispatcher)
+        dispatcher.registry.bluebooks.each_value do |bluebook|
+          chapter = chapter_module(dispatcher, bluebook)
+          Namespace.install(Object, bluebook.name, chapter)
+
+          bluebook.aggregates.each do |aggregate|
+            next if aggregate.hecks_name == bluebook.name
+
+            Namespace.install(Object, aggregate.hecks_name, chapter.const_get(aggregate.hecks_name, false))
+          end
+        end
+        dispatcher
+      end
+    end
+  end
+end

data/lib/hecks/facade.rb

@@ -0,0 +1,44 @@
+module Hecks
+  # The class-free public surface — see facade/surface.rb for the door and
+  # facade/handle.rb for the record in hand. Installed per boot by
+  # `Runtime::Loader.bind_runtime`.
+  module Facade
+  end
+
+  # The one careful way to put something at top level.
+  #
+  # Overwrites only what it itself installed (tracked in GENERATED), refuses —
+  # with a warning, never a raise — to clobber a constant belonging to user
+  # code or the stdlib. Which is why a chapter named `Set` never becomes a
+  # constant, and why `Registry` keeps its own table of chapters rather than
+  # trusting Ruby's. Each re-install REPLACES the previous boot's entry, so
+  # what GENERATED retains is one small facade module per name, not a graph
+  # per boot.
+  module Namespace
+    GENERATED = {}
+
+    module_function
+
+    def install(container, name, value)
+      name = name.to_s
+
+      if container.const_defined?(name, false)
+        current = container.const_get(name)
+        unless GENERATED[[container, name]].equal?(current)
+          warn "[hecks] #{name} is already defined — leaving it alone"
+          return current
+        end
+        container.send(:remove_const, name)
+      end
+
+      container.const_set(name, value)
+      GENERATED[[container, name]] = value
+      value
+    end
+  end
+end
+
+require_relative "facade/handle"
+require_relative "facade/surface"
+require_relative "facade/command_request"
+require_relative "facade/json_door"