hecks 2.8.0 → 3.0.0

data/lib/hecks/{cli → doors}/mcp_door.rb

@@ -1,59 +1,20 @@
 require "json"
 require_relative "../../hecks"
-require_relative "mcp"
+require_relative "../cli/mcp"
 
 module Hecks
-  module CLI
-    # The MCP door onto the storehouse bus: one MCP server for every booted domain,
-    # not one per command, hand-rolled JSON-RPC over stdio (newline-delimited JSON,
-    # flushed after every write, no gem dependency).
+  module Doors
+    # The MCP door onto the storehouse bus: hand-rolled JSON-RPC over stdio, one
+    # server per booted domain. All logic and the JSON shape answered with live in
+    # `Storehouse`; this is plumbing only. A `role:`/`actor_id:` a caller sends is
+    # asserted, not verified, unless Governance is attached.
     #
-    # ## Plumbing only
-    #
-    # All the logic and the JSON shape it answers with live in `Storehouse`, the bus
-    # itself, transport-blind. A door of another shape (a plain CLI, an HTTP door)
-    # would sit beside this one, calling `Storehouse` the same way and sharing its
-    # audit log and caller-identity handling.
-    #
-    # ## Identity is asserted, not verified
-    #
-    # `dispatch` and `query` take `role:` and `actor_id:`, bound for the call through
-    # `Hecks.as_caller`, so a role-gated command is checked against them rather than
-    # merely documented by `describe`; `dispatch` refuses a role-declaring command
-    # called without one. Nothing here verifies the claim beyond the string (or, with
-    # Governance attached, a `Governance::RoleAssignment` lookup). The readers take
-    # no role, and `query` gates on none.
-    #
-    # ## Stdio only, enforced
-    #
-    # The door has no authentication. `Mcp.call` runs
-    # `McpStdioGuard.enforce_stdio!` before this file loads, and `serve` prints the
-    # warning to stderr, never stdout, which carries the protocol. `domain:` is
-    # confined to `Storehouse::BOOT_ROOT` (`confine!`), but a domain within that
-    # root still boots real Ruby, so this is a code execution surface for anyone who
-    # can write to stdin. A network transport needs authentication first; see
-    # `docs/decisions/0062-mcp-servers-need-real-authentication-before-any-network-transport.md`.
-    #
-    # ## Reader mode
-    #
-    # Whoever spawns the door can narrow it with `HECKS_DOOR_TOOLS=readers` and
-    # `HECKS_DOOR_DOMAINS=<dir>[:<dir>...]` (`Hecks::McpDoorScope`, ADR 0072 decision 2).
-    # A reader door serves only `McpDoorScope::READER_TOOLS` (`query`, `events`,
-    # `state`, `catalog`, `describe`, `validate`, `domains`, `history`, `follow`), lists
-    # only those in `tools/list`, and refuses `dispatch` (so `dry_run` and `steps` too),
-    # `behaviors` and any other name with an answer that names the mode. Its `domain:`
-    # must resolve to one of the named directories, checked before anything boots, so no
-    # other domain's Ruby is loaded. The door keeps no domain loaded between calls, so
-    # the named list is the whole allowed set. This limits what one spawned agent can
-    # reach; it identifies no one and is not authentication. The names sit outside
-    # `HECKS_MCP_*` because the stdio guard refuses every name in that prefix but the
-    # transport, and that refusal belongs to ADR 0062. With neither variable set, the
-    # door serves every tool as described above.
-    #
-    # ## One boot per call
-    #
-    # `Hecks.boot(domain, install_facade: false)` is cheap, and it lets one server
-    # answer calls against two domains back to back with no shared, staling state.
+    # There is no authentication: `domain:` boots real Ruby confined to
+    # `Storehouse::BOOT_ROOT`, so this is a code execution surface for anyone who
+    # can write to stdin (ADR 0062). Spawning with `HECKS_DOOR_TOOLS=readers` and
+    # `HECKS_DOOR_DOMAINS=<dir>[:<dir>...]` narrows a door to read-only tools and
+    # named domains (`McpDoorScope`); this limits what one agent can reach and is
+    # not itself authentication.
     module McpDoor
       PROTOCOL_VERSION = "2024-11-05".freeze
 
@@ -271,29 +232,19 @@ module Hecks
 
       module_function
 
-      # The scope this door was spawned with: every tool and any domain, or a reader
-      # door narrowed by `HECKS_DOOR_TOOLS`/`HECKS_DOOR_DOMAINS`. Read once, on first use,
-      # so a bad setting refuses to start the door before anything is written to stdout.
-      #
-      # @return [McpDoorScope]
+      # Read once, so a bad setting refuses to start the door before anything is
+      # written to stdout.
       def scope
-        @scope ||= McpDoorScope.start!(server: Mcp::SERVER)
+        @scope ||= McpDoorScope.start!(server: CLI::Mcp::SERVER)
       end
 
-      # The notes the stdio warning carries: the standing ones, then what this door's
-      # scope says about `domain:`.
-      #
-      # @return [Array<String>]
+      # The standing notes, then what this door's scope says about `domain:`.
       def warning_notes
         NOTES[0, 2] + (scope.restricted? ? scope.notes : [NOTES[2]])
       end
 
-      # Prints the stdio warning to stderr, then answers one JSON-RPC request per
-      # line of `$stdin` until it closes.
-      #
-      # @return [void]
       def serve
-        McpStdioGuard.warn!(server: Mcp::SERVER, notes: warning_notes)
+        McpStdioGuard.warn!(server: CLI::Mcp::SERVER, notes: warning_notes)
         $stdout.sync = true
 
         $stdin.each_line do |line|
@@ -315,29 +266,14 @@ module Hecks
         end
       end
 
-      # Boots one domain for a single call, confined to `Storehouse::BOOT_ROOT`.
-      #
-      # @param domain [String] the domain directory, e.g. `"examples/banking"`
-      # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted domain
-      # @raise [Runtime::TypeMismatch] if `domain` resolves outside `Storehouse::BOOT_ROOT`, or,
-      #   on a reader door, outside `HECKS_DOOR_DOMAINS`
-      # @raise [Runtime::WiringError] if the domain fails to boot
+      # `domain:` is confined to `Storehouse::BOOT_ROOT`, and further to a reader
+      # door's `HECKS_DOOR_DOMAINS`, before anything boots.
       def boot(domain)
-        Hecks.boot(Storehouse.confine!(scope.admit_domain!(domain), "domain"), install_facade: false)
+        Hecks.boot(Storehouse.confine!(scope.admit_domain!(domain), "domain"), install_doors: false)
       end
 
-      # Runs one registered MCP tool by delegating to the matching `Storehouse` call.
-      #
-      # A closed-set dispatch table, one `when` per tool, so the size is the tool
-      # count and the shared `rescue` catches every branch's escape once.
-      #
-      # @param name [String] the tool name, one of `TOOLS`'s own `:name` values
-      # @param args [Hash{String => Object}] the tool's JSON arguments, shaped per that
-      #   tool's `inputSchema`
-      # @return [Hash{Symbol => Object}] the delegated `Storehouse` result on a known
-      #   tool name; `{ok: false, error: String}` for an unknown tool name or any
-      #   `StandardError` this door did not anticipate (a domain refusal is already
-      #   `{ok: false, ...}` from inside `Storehouse` itself)
+      # One `when` per tool, so the shared `rescue` catches every branch's escape
+      # once; a domain refusal is already `{ok: false, ...}` from `Storehouse`.
       def call_tool(name, args) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
         case name
         when "dispatch"
@@ -378,60 +314,29 @@ module Hecks
           { ok: false, error: "no such tool: #{name.inspect} — known: #{TOOLS.map { |t| t[:name] }.join(', ')}" }
         end
       rescue StandardError => e
-        # **A defect, not a refusal** — every domain refusal is already answered as
-        # `{ok: false, error: "..."}` inside `Storehouse`. Reaching here means a bad
-        # domain path or an argument shape `Facade::JsonDoor` could not symbolize,
-        # still answered as structured content rather than an MCP-level `isError`,
-        # so a calling agent reads one shape for every outcome.
+        # A defect, not a refusal: reaching here means a bad domain path or an
+        # argument shape `Doors::JsonDoor` could not symbolize.
         { ok: false, error: "#{e.class}: #{e.message}" }
       end
 
-      # Runs one MCP tool call if this door's mode serves it, and refuses it otherwise.
-      #
-      # @param name [String] the tool name from the `tools/call` request
-      # @param args [Hash{String => Object}] the tool's JSON arguments
-      # @return [Hash{Symbol => Object}] the `call_tool` result, or `scope.refusal(name)`
-      #   when a reader door does not serve `name`
       def answer_tool(name, args)
         return scope.refusal(name) unless scope.permits_tool?(name)
 
         call_tool(name, args)
       end
 
-      # Wraps a `call_tool` payload in the MCP `tools/call` result shape.
-      #
-      # @param payload [Hash{Symbol => Object}] a `call_tool` result
-      # @return [Hash{Symbol => Object}] `{content: [{type: "text", text: ...}], isError: Boolean}`,
-      #   pretty-printing `payload` as the text and setting `isError` from `payload[:ok]`
       def tool_result(payload)
         { content: [{ type: "text", text: JSON.pretty_generate(payload) }], isError: payload[:ok] == false }
       end
 
-      # Writes one JSON-RPC success response line to stdout.
-      #
-      # @param id [String, Integer, nil] the request's own `id`, echoed back
-      # @param result [Object] the JSON-serializable result payload
-      # @return [void]
       def send_response(id, result)
         puts JSON.generate({ jsonrpc: "2.0", id: id, result: result })
       end
 
-      # Writes one JSON-RPC error response line to stdout.
-      #
-      # @param id [String, Integer, nil] the request's own `id`, echoed back; nil when
-      #   the request itself could not be parsed
-      # @param code [Integer] the JSON-RPC error code
-      # @param message [String] the error message
-      # @return [void]
       def send_error(id, code, message)
         puts JSON.generate({ jsonrpc: "2.0", id: id, error: { code: code, message: message } })
       end
 
-      # Dispatches one parsed JSON-RPC request to its method and writes the response.
-      #
-      # @param request [Hash{String => Object}] one parsed JSON-RPC request, with
-      #   `"id"`, `"method"`, and optional `"params"`
-      # @return [void]
       def handle(request)
         id     = request["id"]
         method = request["method"]
@@ -442,7 +347,7 @@ module Hecks
           send_response(id, {
                           protocolVersion: PROTOCOL_VERSION,
                           capabilities:    { tools: {} },
-                          serverInfo:      { name: Mcp::SERVER, version: "1.1.0" }
+                          serverInfo:      { name: CLI::Mcp::SERVER, version: "1.1.0" }
                         })
         when "notifications/initialized"
           nil # a notification — no id, no response

data/lib/hecks/doors/mcp_door_scope.rb

@@ -0,0 +1,97 @@
+require_relative "../runtime/errors"
+
+module Hecks
+  module Doors
+    # What a spawned hecks mcp may do: every tool by default, or only
+    # reader tools against named domains in reader mode — reach, not identity (ADR 0072).
+    class McpDoorScope
+      ENV_PREFIX       = "HECKS_DOOR_".freeze
+      TOOLS_VARIABLE   = "HECKS_DOOR_TOOLS".freeze
+      DOMAINS_VARIABLE = "HECKS_DOOR_DOMAINS".freeze
+      READERS          = "readers".freeze
+      EXIT_STATUS      = 2
+
+      # The tools a reader door serves — each reads a domain or the door's own
+      # audit log and writes no domain state. `validate` still boots its
+      # domain, so it stays bound to the allowed set like every other tool.
+      READER_TOOLS = %w[query events state catalog describe validate domains history follow].freeze
+
+      # Unrestricted when no HECKS_DOOR_* variable is set.
+      def self.from_env(env = ENV)
+        problems = setting_problems(env)
+        raise ArgumentError, problems.join("\n") unless problems.empty?
+        return new(allowed_domains: nil) unless env[TOOLS_VARIABLE]
+
+        new(allowed_domains: env[DOMAINS_VARIABLE].split(File::PATH_SEPARATOR).reject(&:empty?))
+      end
+
+      # Refuses to stderr, not stdout, which carries the MCP protocol.
+      def self.start!(server:, env: ENV, stderr: $stderr)
+        from_env(env)
+      rescue ArgumentError, Runtime::TypeMismatch => e
+        e.message.each_line { |line| stderr.puts("#{server}: refusing to start: #{line.chomp}") }
+        exit(EXIT_STATUS)
+      end
+
+      def self.setting_problems(env)
+        unknown = env.keys.select { |name| name.start_with?(ENV_PREFIX) } - [TOOLS_VARIABLE, DOMAINS_VARIABLE]
+        problems = unknown.map do |name|
+          "environment #{name} is not accepted; the door takes only #{TOOLS_VARIABLE} and #{DOMAINS_VARIABLE}"
+        end
+        problems + mode_problems(env[TOOLS_VARIABLE], env[DOMAINS_VARIABLE])
+      end
+
+      def self.mode_problems(tools, domains)
+        if tools.nil?
+          domains.nil? ? [] : ["#{DOMAINS_VARIABLE} is set without #{TOOLS_VARIABLE}=#{READERS}; it only narrows a reader door"]
+        elsif tools != READERS
+          ["#{TOOLS_VARIABLE}=#{tools.inspect} is not accepted; the only value is #{READERS.inspect}"]
+        elsif domains.to_s.split(File::PATH_SEPARATOR).none? { |path| !path.empty? }
+          ["#{TOOLS_VARIABLE}=#{READERS} needs #{DOMAINS_VARIABLE}, the domains this door may read"]
+        else
+          []
+        end
+      end
+
+      # The named domains, resolved against Storehouse::BOOT_ROOT; nil when unrestricted.
+      attr_reader :allowed_domains
+
+      def initialize(allowed_domains:)
+        @allowed_domains = allowed_domains&.map { |path| Storehouse.confine!(path, DOMAINS_VARIABLE) }.freeze
+      end
+
+      def restricted?
+        !@allowed_domains.nil?
+      end
+
+      def permits_tool?(name)
+        !restricted? || READER_TOOLS.include?(name)
+      end
+
+      def refusal(name)
+        { ok:    false,
+          error: "#{name.inspect} is refused: this door runs in reader mode (#{TOOLS_VARIABLE}=#{READERS}), " \
+                 "which serves only #{READER_TOOLS.join(', ')}" }
+      end
+
+      # Checked before anything boots, so a path outside the allowed set never reaches Kernel.load.
+      def admit_domain!(domain)
+        return domain unless restricted?
+        return domain if @allowed_domains.include?(Storehouse.confine!(domain, "domain"))
+
+        raise Runtime::TypeMismatch,
+              "domain: #{domain.inspect} is refused: this door runs in reader mode (#{TOOLS_VARIABLE}=#{READERS}) " \
+              "and reads only #{DOMAINS_VARIABLE}: #{@allowed_domains.join(', ')}"
+      end
+
+      def notes
+        return [] unless restricted?
+
+        ["Reader mode (#{TOOLS_VARIABLE}=#{READERS}): serves #{READER_TOOLS.join(', ')}; " \
+         "refuses dispatch (with dry_run and steps), behaviors and every other tool.",
+         "domain: boots only #{DOMAINS_VARIABLE}: #{@allowed_domains.join(', ')}.",
+         "Reader mode limits reach and identifies no one; it is not authentication."]
+      end
+    end
+  end
+end

data/lib/hecks/doors/ruby_door/aggregate_door.rb

@@ -0,0 +1,162 @@
+require_relative "../../bluebook/dsl/hecksagon_builder"
+require_relative "../../bluebook/dsl/world_builder"
+require_relative "../../bluebook/dsl/domain_port_builder"
+require_relative "../../bluebook/dsl/const_shim"
+require_relative "../../bluebook/dsl/binding_proxy"
+require_relative "../../bluebook/hexagon"
+require_relative "../handle"
+require_relative "../../naming"
+
+module Hecks
+  module Doors
+    module RubyDoor
+      # One aggregate's door: creating verbs and queries as module methods, CRUD
+      # delegation, and the `.hecksagon` binding/port hooks it lands on.
+      module AggregateDoor
+        # Builds one aggregate's door module: creating-command methods, query methods,
+        # find/all/count/events, project/docs/narrate, and the port/binding hooks.
+        #
+        # Kept as one method: `:port`/`:method_missing`/`:const_missing` below
+        # cross-reference each other and would lose that thread if split up.
+        # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+        def aggregate_module(dispatcher, domain, aggregate)
+          fqn  = "#{domain}::#{aggregate.hecks_name}"
+          door = Module.new
+
+          aggregate.attributes.each do |attribute|
+            next unless RESERVED.include?(attribute.name.to_sym)
+
+            warn "[hecks] #{aggregate.hecks_name}##{attribute.name} shadows a built-in — no reader defined"
+          end
+
+          # `!` marks a creating command (Ruby's mutate-and-may-refuse convention).
+          # Without it, a query sharing the same business name (e.g. Account's
+          # "Open") would collide with the creating command's own bare name.
+          aggregate.commands.select(&:creates?).each do |command|
+            door.define_singleton_method("#{Naming.snake(command.hecks_name)}!") do |**args|
+              Handle.new(dispatcher: dispatcher, domain: domain, aggregate: aggregate,
+                         instance: dispatcher.dispatch("#{fqn}.#{command.hecks_name}", with: args).instance)
+            end
+          end
+
+          # A query is a bare module method (no `!`): it just reads and returns
+          # the same raw row array `dispatcher.query` itself answers.
+          aggregate.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)         { aggregate }
+
+          # Every construct emits its own IR, so an aggregate is a legitimate
+          # `project` target too. A chapter-scoped target refuses here via
+          # `Projector.admits!` rather than answering a confidently empty result.
+          door.define_singleton_method(:project) do |target, out: nil, **options|
+            key      = Projector.key_for(target)
+            artifact = Projector.call(key, bluebook: aggregate, 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, aggregate) }
+          door.define_singleton_method(:commands) do
+            aggregate.commands.map { |c| "#{Naming.snake(c.hecks_name)}!" }.sort
+          end
+          door.define_singleton_method(:queries) { aggregate.queries.map { |q| Naming.snake(q.hecks_name) }.sort }
+          # This chapter's own `:docs` projection, narrowed to this aggregate.
+          door.define_singleton_method(:docs) do |**options|
+            Projector.call(:docs, bluebook: dispatcher.registry.bluebook(domain),
+                                  options:  options.merge(aggregate: aggregate.hecks_name))
+          end
+          # Same narrowing as `:docs`, aimed at `:narrate`.
+          door.define_singleton_method(:narrate) do |**options|
+            Projector.call(:narrate, bluebook: dispatcher.registry.bluebook(domain),
+                                     options:  options.merge(aggregate: aggregate.hecks_name))
+          end
+          door.define_singleton_method(:count)      { dispatcher.registry.repository(domain, aggregate).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, aggregate).find(id)
+            found && Handle.new(dispatcher: dispatcher, domain: domain, aggregate: aggregate, instance: found)
+          end
+
+          door.define_singleton_method(:all) do |**opts|
+            dispatcher.registry.repository(domain, aggregate).all(**opts).map do |instance|
+              Handle.new(dispatcher: dispatcher, domain: domain, aggregate: aggregate, instance: instance)
+            end
+          end
+
+          # Re-resolves via `Hecks.current_registry` rather than the closed-over
+          # `aggregate`: this door can be stale from an earlier boot, and its own
+          # `aggregate` would silently port a discarded one instead of the live one.
+          door.define_singleton_method(:port) do |name, &block|
+            current = Hecks.current_registry&.bluebook(domain)&.aggregate(aggregate.hecks_name) or
+              raise Bluebook::DSL::Malformed, "#{fqn}.port(#{name.inspect}) called outside a boot"
+
+            built = Bluebook::DSL::ConstShim.with(->(const) { const }) do
+              Bluebook::DSL::DomainPortBuilder.build(name, owner: current.hecks_name, &block)
+            end
+
+            # A `verb`-shaped port is a plain `Port`, the same struct `Hecks.port` registers —
+            # it belongs to no aggregate IR the way an operations-shaped `DomainPort` does, so
+            # it takes the registry's `add_port` directly. Mirrors `DSL::BindingProxy#port`,
+            # which handles the identical shape on a domain's first in-process boot (before
+            # this facade constant exists); this method is what a repeat boot reaches instead.
+            if built.is_a?(Bluebook::Port)
+              Hecks.current_registry.add_port(built)
+              return self
+            end
+
+            built.operations.each do |operation|
+              operation.attributes.select(&:reference?).each { |attribute| attribute.type.declared_in = current }
+            end
+            current.add_port(built)
+            self
+          end
+
+          door.define_singleton_method(:method_missing) do |verb, *args, **kwargs, &block|
+            # A bare call starts a Privacy marking chain (see
+            # `BindingProxy#method_missing`), reached here when the door is already
+            # installed (a second in-process boot) rather than at parse time.
+            return Bluebook::DSL::AttributePath.new(fqn, [verb.to_s]) if args.empty? && kwargs.empty? && !block
+
+            collector = Bluebook::DSL::HecksagonBuilder.collector
+            world     = Bluebook::DSL::WorldBuilder.current
+            # Inside a `.world` block the same qualified spelling records a world setting.
+            return world.record_binding(verb, args, kwargs, block) if world && !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? || !Bluebook::DSL::WorldBuilder.current.nil? ||
+              super(name, include_private)
+          end
+
+          # Uses `aggregate.hecks_name`, not the qualified `fqn`: qualifying it here
+          # would make `Account::Debit`'s meaning depend on whether a stale door
+          # from an earlier boot happens to be sitting on this process.
+          door.define_singleton_method(:const_missing) do |name|
+            resolver = Bluebook::DSL::ConstShim.resolver
+            return resolver.call("#{aggregate.hecks_name}::#{name}") if resolver
+
+            super(name)
+          end
+
+          door
+        end
+      end
+    end
+  end
+end

data/lib/hecks/doors/ruby_door/chapter.rb

@@ -0,0 +1,72 @@
+require_relative "../../bluebook/dsl/binding_proxy"
+require_relative "../../bluebook/dsl/const_shim"
+require_relative "../../bluebook/dsl/hecksagon_builder"
+
+module Hecks
+  module Doors
+    module RubyDoor
+      # One chapter's module: vision and aggregate list on the singleton, one
+      # aggregate door per declared head, and a `const_missing` hook for undeclared names.
+      module Chapter
+        # Builds the anonymous module that stands for one booted chapter: `vision`,
+        # `aggregates`, `docs`, `narrate` and `project` as singleton methods, plus one
+        # nested constant per aggregate holding that aggregate's door.
+        #
+        # @param dispatcher [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted
+        #   dispatcher each aggregate door closes over
+        # @param bluebook [Bluebook::Chapter] the chapter to project into a module
+        # @return [Module] a fresh, unnamed module; `RubyDoor.install` gives it its
+        #   top-level name
+        # @raise [NameError] if an aggregate's name is not a valid constant name
+        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's usage document, projected from its IR on each call so it
+          # cannot go stale.
+          chapter.define_singleton_method(:docs) do |**options|
+            Projector.call(:docs, bluebook: bluebook, options: options)
+          end
+
+          # The chapter read back in english, via `Projector::NarrateProjector`.
+          chapter.define_singleton_method(:narrate) do |**options|
+            Projector.call(:narrate, bluebook: bluebook, options: options)
+          end
+
+          # Projects the chapter's IR through a target; `out:` writes the artifact and
+          # the remaining options go to the projector (`audience:` for OIDC).
+          #
+          #   Pizzas.project(Projections::OIDC)
+          #   Pizzas.project(Projections::Shape, out: "shape.json")
+          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: with a collector open it becomes
+          # a `BindingProxy`. Otherwise a scoped reference from a bluebook mid-declaration
+          # goes to the `ConstShim` resolver, so it resolves whether or not a facade exists.
+          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/doors/ruby_door.rb

@@ -0,0 +1,77 @@
+require_relative "../chapters"
+require_relative "ruby_door/chapter"
+require_relative "ruby_door/aggregate_door"
+
+module Hecks
+  module Doors
+    # The door without classes: anonymous per-boot modules whose singleton methods
+    # dispatch by FQN, installed by `Loader.bind_runtime` and replaced whole on the next boot.
+    #
+    # `persisted_by("Heki")` in a `.hecksagon` file lands on the module's `method_missing`,
+    # which records a `Bind` into the open `HecksagonBuilder.collector`.
+    module RubyDoor
+      # Names that would shadow the machinery a Handle runs on; a field with one gets no reader.
+      RESERVED = %i[id state events reload inspect to_h hash class].freeze
+
+      extend Chapter
+      extend AggregateDoor
+
+      module_function
+
+      # Installs one top-level module per booted chapter, and one per aggregate, each
+      # closing over `dispatcher`, so `Pizzas::Pizza` and the bare `Pizza` both open the
+      # door of the boot that ran last.
+      #
+      # A gem chapter a hecksagon `attaches` installs nothing (`Query`, `Port` stay free).
+      # An aggregate sharing its chapter's name gets no second constant. A name that user
+      # code or the stdlib already owns is left alone with a warning (see `Namespace.install`).
+      #
+      # @param dispatcher [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted
+      #   dispatcher every installed door dispatches and queries through
+      # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] the same `dispatcher`
+      # @raise [NameError] if a chapter or aggregate name is not a valid constant name
+      def install(dispatcher)
+        dispatcher.registry.bluebooks.each_value do |bluebook|
+          next if attached_chapter?(dispatcher.registry, bluebook)
+
+          chapter = chapter_module(dispatcher, bluebook)
+          Namespace.install(*placement(bluebook), chapter)
+          # A namespaced chapter keeps its aggregates inside its namespace: top-level
+          # shortcuts would bring back the collisions the namespace exists to avoid.
+          next if bluebook.namespace
+
+          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
+
+      # Whether `bluebook` is a gem chapter that a hecksagon attached rather than a domain's own.
+      #
+      # @param registry [Runtime::Registry] the booted registry
+      # @param bluebook [Bluebook::Chapter] the chapter under test
+      # @return [Boolean]
+      def attached_chapter?(registry, bluebook)
+        registry.bounded?(bluebook.name) && Hecks::Chapters.index.key?(bluebook.name)
+      end
+
+      # Where a chapter's module installs: `Object::<name>`, or the constant path its
+      # `namespace` names, creating any missing parent modules along the way.
+      #
+      # @param bluebook [Bluebook::Chapter] the chapter being installed
+      # @return [Array(Module, String)] the parent module and the constant name within it
+      def placement(bluebook)
+        return [Object, bluebook.name] unless bluebook.namespace
+
+        *parents, leaf = bluebook.namespace.split("::")
+        parent = parents.reduce(Object) do |outer, name|
+          outer.const_defined?(name, false) ? outer.const_get(name, false) : outer.const_set(name, Module.new)
+        end
+        [parent, leaf]
+      end
+    end
+  end
+end