hecks 0.2.0 → 0.3.0

data/lib/hecks/facade/json_door.rb

@@ -0,0 +1,154 @@
+require "json"
+require_relative "handle"
+require_relative "command_request"
+require_relative "../naming"
+require_relative "../runtime/errors"
+require_relative "../runtime/value"
+
+module Hecks
+  module Facade
+    # THE JSON DOOR — WHERE Facade MEETS BODY-IN/BODY-OUT CALLERS.
+    #
+    # `Handle`/`Surface` are Ruby sugar over the dispatcher for a Ruby caller
+    # holding real objects — a symbol verb name, a `**kwargs` payload, a
+    # `Handle` back in hand. A REST-ish JSON API is a caller holding STRINGS
+    # instead: a URL segment naming a collection, a URL segment naming a
+    # record or a verb, a parsed request body whose every key arrived as a
+    # String because that is all JSON ever gives. Every app that wants to put
+    # a JSON API in front of a booted domain has to do that translation —
+    # name to class, string to symbol, nested `Runtime::Value` back to plain
+    # data — and one sibling app had already hand-written it once, bespoke,
+    # against its own routes, before this existed. This is that translation
+    # pulled out, generic, reading the SAME IR the rest of the facade already
+    # reads rather than re-deriving "how do I find an aggregate by name".
+    #
+    # NO HTTP LIVES HERE. Same discipline `Router` and `Surface` already
+    # hold: this module never sees a request object, never picks a status
+    # code, never calls `halt`. Every method here takes plain Ruby values in
+    # — a raw JSON String is the one exception, see `.parse` below, every
+    # other input is already-parsed data — and returns plain Ruby values
+    # out, or raises. Turning a raw request body into that input, and
+    # turning a raised exception into an HTTP status, both stay the calling
+    # app's job, exactly the way they already are for `Router#dispatch`.
+    #
+    # EVERY "THAT DOESN'T EXIST" CASE RAISES `Runtime::NotFound` — THE SAME
+    # CLASS EVERY TIME, NOT A NEW ONE PER CALLER. `Runtime::NotFound` already
+    # sits in `Runtime::DOMAIN_REFUSALS` (runtime/errors.rb) — the family a
+    # booted app already has, or trivially can have, ONE generic `error`
+    # handler for, mapping the whole family to a status code without a
+    # special case per refusal. A bespoke `JsonDoor::CollectionNotFound` (or
+    # three of those, one per flavor of "not found") would just force every
+    # app that adopts this door to widen its rescue clause to match it — the
+    # opposite of what a shared refusal family is for. So "no such
+    # aggregate", "no creating command", "no such command", and "no record
+    # with that id" all raise the one class, distinguished only by message.
+    module JsonDoor
+      module_function
+
+      # "Banking", "Customer" -> the `Banking::Customer` class `.find` /
+      # `.create_...` / etc already answer for — the same class
+      # `Facade::Handle`'s own reference accessors reach with
+      # `Object.const_get` (see handle.rb's `define_reference_accessors`).
+      #
+      # Checked against the CURRENT boot's IR first, not against Ruby's
+      # constant table directly — a name that names nothing in this
+      # registry should refuse before ever asking Ruby whether some
+      # same-named constant happens to exist (possibly a stale one, left
+      # over from an earlier boot in this same process — the exact hazard
+      # `AggregateDoor#port`'s own comment describes at length). Only once
+      # the IR confirms the aggregate is real does this read the constant
+      # the current boot's `Surface.install` actually minted for it.
+      def aggregate(dispatcher, domain, name)
+        ir = dispatcher.registry.bluebook(domain)&.aggregate(name)
+        raise Runtime::NotFound, "#{domain} declares no aggregate named #{name.inspect}" unless ir
+
+        Object.const_get("#{domain}::#{ir.hecks_name}")
+      end
+
+      # The one command a POST to a bare collection URL means — "make one of
+      # these". `AggregateDoor` already enforces exactly one creating
+      # command per aggregate (`Command#creates?`, true exactly when the
+      # command declares no `references`); this just names it the same
+      # snake_case-plus-bang a Ruby caller would already ask the door for
+      # (`Naming.snake`, the identical call `AggregateDoor` itself makes
+      # when it defines that singleton method in the first place — `!`
+      # because every command does now, door and Handle alike).
+      def creating_command(klass)
+        creating = klass.ir.commands.find(&:creates?)
+        raise Runtime::NotFound, "#{klass.ir.hecks_name} declares no creating command" unless creating
+
+        "#{Naming.snake(creating.hecks_name)}!"
+      end
+
+      # A URL segment or a JSON body's "command" field, checked against what
+      # the aggregate actually declares. `klass.commands` is the same
+      # sorted, snake_cased list `AggregateDoor` built for its own door, so
+      # a name this accepts is a name a `Handle` can actually dispatch.
+      def validate_command!(klass, name)
+        wanted = name.to_s
+        return wanted if klass.commands.include?(wanted)
+
+        raise Runtime::NotFound, "#{klass.ir.hecks_name} declares no command named #{wanted.inspect}"
+      end
+
+      # `klass.find` already answers nil-on-miss — the right shape for a
+      # Ruby caller that means to check for itself. A JSON caller asking for
+      # one record by id off a URL means to HAVE it, or answer 404 — this is
+      # that stricter wrapper, raising the same `Runtime::NotFound` the rest
+      # of this door raises rather than handing back nil for the caller to
+      # remember to check.
+      def find!(klass, id)
+        klass.find(id) or raise Runtime::NotFound, "no #{klass.ir.hecks_name} found for id #{id.inspect}"
+      end
+
+      # JSON only ever hands back String keys. A command's args, and every
+      # nested value-object literal inside them, need symbol keys before
+      # `Handle`/`Dispatcher` will accept them at all — this is that
+      # recursive conversion, blind to how deep a body nests.
+      def deep_symbolize(value)
+        case value
+        when Hash  then value.to_h { |k, v| [k.to_sym, deep_symbolize(v)] }
+        when Array then value.map { |item| deep_symbolize(item) }
+        else value
+        end
+      end
+
+      # The other direction: a `Handle`, or a query row's plain state hash,
+      # carrying a `Runtime::Value` at every level a value object sits at —
+      # down to plain Ruby a JSON encoder can walk without knowing what a
+      # `Runtime::Value` is.
+      #
+      # `Runtime::Value.materialize` (runtime/value.rb) already does the
+      # actual recursion — its `Hash` branch calls itself on every value,
+      # its `Value` branch unwraps through `#to_h`, which itself calls
+      # `materialize` on every field, so a value object three levels deep
+      # unwraps three levels deep for free. This is not a second unwrapper
+      # sitting next to it: `materialize` covers `Hash`/`Array`/`Value`
+      # already, and a `Handle` is none of those three, so the one thing
+      # this adds is `#to_h`'ing a `Handle` first so `materialize`'s own
+      # `Hash` case can take it from there.
+      def materialize(value)
+        value = value.to_h if value.is_a?(Handle)
+        Runtime::Value.materialize(value)
+      end
+
+      # Parsed JSON and raw JSON text cross the same receiver/payload boundary
+      # as CLI and forms. The result is ready to splat into Dispatcher#dispatch
+      # and contains no loose routing fields.
+      def command_request(body, receiver:, legacy_receiver: nil)
+        input = body.is_a?(String) ? parse(body) : body
+        CommandRequest.normalize(input, receiver: receiver, legacy_receiver: legacy_receiver)
+      end
+
+      # The one place a raw JSON string is legitimate input for this door —
+      # a POST body, still text at the point a generic, HTTP-blind layer can
+      # see it. `JSON::ParserError` already names "this wasn't JSON" exactly
+      # right ; wrapping it in a bespoke `JsonDoor`-specific class would
+      # only be a second name for the same fact, so it propagates exactly as
+      # `JSON.parse` raises it — a calling app catches it the same standard
+      # way it would catch any other malformed-input error, no new class to
+      # learn.
+      def parse(raw_json) = JSON.parse(raw_json)
+    end
+  end
+end

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"