hecks 2.9.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f6baf48801bf4f341c3a39a05215c2a0ce3f345b22068f84d0e04c91c3c76f6
-  data.tar.gz: 6eda1623f06f2607400ff7a2b13c10775ed60416c91f36f7d4a36bdb9d6adf39
+  metadata.gz: c04beedd84550f06db74d93d28c907eee4a0a913f6dfb619d84a1844faefeb13
+  data.tar.gz: 7b3cf71a37bbc83fa80c14eace35831f4b9bceaa789affbda6e2b1158e1ef39e
 SHA512:
-  metadata.gz: c8d8670a30de7d7318a84cf6a25f78b394c6974fb42f61697fbe20d0bc5642455740c644fd055cfe7f347d0bed254ab93fd42ce596fc444af6de8bcde86e7291
-  data.tar.gz: dc3b18d73758d235d369c0158729b8186e8d6a6d8c2c5040d26f772876b43d8ff8eb29a784e166585af1d890bf5620de0fa456934bf6568ba96d1318858e9079
+  metadata.gz: fdf38f7f5ece37807699026ff6166408f948a827aa59d4cec712ad48a686a90d932ec49ac083853a141654a50bfbc1ade18a0c3538126821ecb187128966c155
+  data.tar.gz: 03ccb78bc4b99292abc6e39ae74b35179254583fb41f735f116da2cacec4709971c8eb36c02fdc0e0ebe13b742b58311fe8e01dd1731e2c40efcaa0a430dcbf4

data/exe/hecks

@@ -1,11 +1,56 @@
 #!/usr/bin/env ruby
 
-# The `hecks` command the gem installs: run, read, check and serve a domain.
-# Routes to `Hecks::CLI` (lib/hecks/cli.rb); run with no arguments to list subcommands.
+# Hecks's command line — GENERATED by hecks project_cli. Do not edit.
+#
+# A launcher, not a CLI: the verbs, their arguments and their refusals are
+# projected from the bluebook beside it every time this runs, so a change
+# to the chapter shows up here without re-minting anything.
+#
+#   exe/hecks                  every verb, and every question
+#   exe/hecks <verb> --help    what it wants, and how it refuses
+
+Encoding.default_external = Encoding::UTF_8
+Encoding.default_internal = Encoding::UTF_8
 
-# The gem's own `lib` goes first, as for every `bin/` script, so this also
-# runs straight from a checkout.
 $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
-require "hecks/cli"
 
-exit Hecks::CLI.start(ARGV)
+# The names the gem has always shipped keep their positional forms.
+LEGACY = %w[run docs narrate ir stores model_check smoke_test project_diagrams project_cli mcp].freeze
+if LEGACY.include?(ARGV.first)
+  require "hecks/cli"
+  exit Hecks::CLI.start(ARGV) unless Hecks::CLI.launcher_form?(ARGV)
+end
+
+require "hecks"
+
+# Usage is answered from the projected chapter alone: no adapter is bound and no
+# database is opened. Only a line that runs a verb boots the domain.
+domain = File.expand_path("../lib/hecks/hecks", __dir__)
+program = "hecks"
+described = begin
+  Hecks.describe(domain)
+rescue StandardError => e
+  abort "cannot open Hecks: #{e.message.lines.first.strip}"
+end
+
+text, status, reason = Hecks::Doors::CliRunner.usage(
+  runtime: described, argv: ARGV, program: program
+)
+unless text
+  runtime = begin
+    Hecks.boot(domain, install_doors: false)
+  rescue StandardError => e
+    abort "cannot open Hecks: #{e.message.lines.first.strip}"
+  end
+  text, status, reason = Hecks::Doors::CliRunner.call(
+    runtime: runtime, argv: ARGV, program: program
+  )
+end
+# A `--wait` run that failed answers its settled record on stdout, so `| jq` reads it
+# either way, and says why on stderr.
+if reason
+  puts text
+  warn reason
+  exit status
+end
+status.zero? ? puts(text) : abort(text)

data/lib/hecks/adapters/driven/heki/journal.rb

@@ -24,7 +24,7 @@ module Hecks
 
         # Folds the journal into the snapshot and truncates it. Opt-in; never run after a save.
         #
-        # This discards the history `entries` returns, which projections and `bin/history`
+        # This discards the history `entries` returns, which projections and `hecks history`
         # read in full, so use it only on an aggregate nothing projects from.
         #
         # The snapshot is written durably before the journal is truncated; a crash between

data/lib/hecks/adapters/driven/lambda/client.rb

@@ -7,7 +7,7 @@ module Hecks
       # Runtime::RemoteDispatcher's writes: one Lambda invoke, one JSON round trip.
       #
       # The function name defaults to `"hecks-#{domain.downcase}"`, matching
-      # `bin/project_deploy`'s `stack_name` computation. A domain whose stack
+      # `hecks deploy project`'s `stack_name` computation. A domain whose stack
       # name doesn't follow that pattern must pass `function` explicitly, via
       # a `.world`'s `persisted_by("Lambda")`/`dispatched_by("Lambda")` block.
       class Client

data/lib/hecks/adapters/driven/lambda.rb

@@ -38,7 +38,7 @@ module Hecks
         function = setting(settings, :function, nil)
         # `domain` only prefixes the instances lookup; the function to call is named by
         # DOMAIN_NAME (set in a deployed Lambda, where root is always /var/task), else by
-        # root's basename, which matches bin/project_deploy's stack name on a local boot.
+        # root's basename, which matches hecks deploy project's stack name on a local boot.
         function_domain = ENV["DOMAIN_NAME"] || (root ? File.basename(root) : domain)
         @client = Client.new(domain: function_domain, region: region, function: function)
         @prefix = "#{domain}::#{aggregate.hecks_name}#"

data/lib/hecks/adapters/driven/memory.rb

@@ -34,6 +34,7 @@ module Hecks
         @events    = []
         @entries   = []
         @outbox    = []
+        @outbox_deliveries = {}
       end
 
       # Looks up the current record for one aggregate identity.
@@ -162,6 +163,7 @@ module Hecks
         @events  = []
         @entries = []
         @outbox  = []
+        @outbox_deliveries = {}
         self
       end
 
@@ -185,10 +187,11 @@ module Hecks
       #   was a duplicate
       def outbox_enqueue(rows)
         rows.filter_map do |row|
-          next nil if @outbox.any? { |held| held.delivery_id == row.delivery_id }
+          next nil if @outbox_deliveries.key?(row.delivery_id)
 
           row.id = @outbox.size + 1
           @outbox << row
+          @outbox_deliveries[row.delivery_id] = true
           row
         end
       end
@@ -199,7 +202,7 @@ module Hecks
       # @return [Boolean] true when the row was pending and is now claimed; false when it is
       #   unknown or not pending
       def outbox_claim(id) # rubocop:disable Naming/PredicateMethod
-        row = @outbox.find { |held| held.id == id }
+        row = outbox_row(id)
         return false unless row&.pending?
 
         row.status = "claimed"
@@ -215,7 +218,7 @@ module Hecks
       # @param error [String, nil] the failure description, or nil to clear it
       # @return [Boolean] true when the row exists and was updated; false when no row has `id`
       def outbox_settle(id, status:, error: nil) # rubocop:disable Naming/PredicateMethod
-        row = @outbox.find { |held| held.id == id } or return false
+        row = outbox_row(id) or return false
         row.status = status.to_s
         row.error  = error
         true
@@ -233,6 +236,16 @@ module Hecks
 
       private
 
+      # Finds a held outbox row by id in constant time.
+      #
+      # Ids are assigned as the 1-based position at enqueue and rows are never
+      # removed, so the id is the row's index plus one.
+      def outbox_row(id)
+        return nil unless id.is_a?(Integer) && id >= 1
+
+        @outbox[id - 1]
+      end
+
       # Skips the codec copy and rehydration round trip while judging the
       # self-hosted grammar (S17, ADR 0026), where re-validating already-valid
       # entity state costs O(N) per save and O(N^2) across an N-row table.

data/lib/hecks/adapters/driven/postgres/reconnect.rb

@@ -38,8 +38,12 @@ module Hecks
       # The failing call still raises and is never retried: it may have reached the server.
       # A failed reconnect is swallowed so it does not mask the original error.
       def reconnect!
-        @db = self.class.connect_for(@aggregate.name, @settings)
-      rescue PG::Error
+        if @db.respond_to?(:reconnect!)
+          @db.reconnect!
+        else
+          @db = self.class.connect_for(@aggregate.name, @settings)
+        end
+      rescue PG::Error, Runtime::WiringError
         nil
       end
     end

data/lib/hecks/adapters/driven/postgres/shared_connection.rb

@@ -0,0 +1,180 @@
+require "monitor"
+
+module Hecks
+  module Adapters
+    # One Postgres connection shared by every `Postgres` or `PostgresEra` adapter of a process
+    # that targets the same database and schema, so a domain's connection count does not grow
+    # with its aggregates. Each adapter class shares only with its own kind, because each opens
+    # its connection its own way.
+    #
+    # Every call runs under one re-entrant monitor, and a transaction holds it from BEGIN to
+    # COMMIT, so a second thread's statements never interleave into another thread's
+    # transaction. The owning thread re-enters freely, so a nested `transaction` joins the open
+    # one, whichever aggregate's adapter opened it.
+    class PostgresSharedConnection
+      REGISTRY = {} # rubocop:disable Style/MutableConstant
+      REGISTRY_LOCK = Mutex.new
+      private_constant :REGISTRY, :REGISTRY_LOCK
+
+      # Runs in a forked child right after the fork, before any of its code.
+      #
+      # A child inherits its parent's sockets, and libpq sends a Terminate on the socket when
+      # the child's copy of the connection is finalized at exit, which would end the parent's
+      # session. The child's copy of each socket fd is pointed at the null device, so that
+      # Terminate goes nowhere, and the child forgets the handles without `finish`.
+      #
+      # @return [void]
+      def self.disown_inherited!
+        REGISTRY.each_value(&:disown!)
+        REGISTRY.clear
+      end
+
+      # Prepended to `Process` so every `fork`, `Process.fork` and `Kernel#fork` disowns the
+      # shared connections in the child.
+      module ForkGuard
+        # @return [Integer, nil] the child's pid in the parent, nil in the child
+        def _fork
+          pid = super
+          PostgresSharedConnection.disown_inherited! if pid.zero?
+          pid
+        end
+      end
+      Process.singleton_class.prepend(ForkGuard)
+
+      # Returns the process's shared connection for a database and schema, opening it on first use.
+      #
+      # The key includes the pid, so a forked child opens its own instead of sharing its
+      # parent's socket.
+      #
+      # @param name [String] the domain or aggregate name, used only in refusal messages
+      # @param settings [Hash{Symbol, String => Object}] `database` and optional `schema`
+      # @param connector [#connect_for] the adapter class that opens the connection
+      # @return [PostgresSharedConnection] the shared handle, connected
+      # @raise [Runtime::WiringError] if `database` is missing or the connection is refused
+      def self.for(name, settings, connector:)
+        key = [Process.pid, connector, setting(settings, :database), setting(settings, :schema)]
+        REGISTRY_LOCK.synchronize do
+          handle = REGISTRY[key] ||= new(name, settings, connector: connector)
+          handle.reconnect! if handle.dead?
+          handle
+        end
+      end
+
+      # Reads one setting under its Symbol or String spelling as a string.
+      #
+      # @param settings [Hash{Symbol, String => Object}] the binding's settings
+      # @param key [Symbol] the setting's name
+      # @return [String] the value, empty when absent
+      def self.setting(settings, key)
+        (settings.key?(key) ? settings[key] : settings[key.to_s]).to_s
+      end
+      private_class_method :setting
+
+      # Counts the shared connections this process holds open.
+      #
+      # @return [Integer] how many database and schema pairs have a live shared connection
+      def self.open_count = REGISTRY_LOCK.synchronize { REGISTRY.values.count { |handle| !handle.dead? } }
+
+      # Closes every shared connection and forgets it; the next `for` opens a fresh one.
+      #
+      # @return [void]
+      def self.close_all!
+        REGISTRY_LOCK.synchronize do
+          REGISTRY.each_value(&:close)
+          REGISTRY.clear
+        end
+      end
+
+      # @param name [String] the domain or aggregate name, used only in refusal messages
+      # @param settings [Hash{Symbol, String => Object}] `database` and optional `schema`
+      # @param connector [#connect_for] the adapter class that opens the connection
+      # @raise [Runtime::WiringError] if `database` is missing or the connection is refused
+      def initialize(name, settings, connector:)
+        @name = name
+        @settings = settings
+        @connector = connector
+        @monitor = Monitor.new
+        @conn = connector.connect_for(name, settings)
+      end
+
+      # Runs one parameterless statement under the connection's monitor.
+      #
+      # @param sql [String] the statement
+      # @return [PG::Result] the statement's result
+      def exec(sql, &) = @monitor.synchronize { @conn.exec(sql, &) }
+
+      # Runs one statement with bind parameters under the connection's monitor.
+      #
+      # @param sql [String] the statement, with `$1`-style placeholders
+      # @param binds [Array<Object>] one value per placeholder
+      # @return [PG::Result] the statement's result
+      def exec_params(sql, binds = [], *rest, &) = @monitor.synchronize { @conn.exec_params(sql, binds, *rest, &) }
+
+      # Reports the server-side transaction state; blocks while another thread's transaction
+      # holds the connection, so a caller never mistakes it for its own.
+      #
+      # @return [Integer] a `PG::PQTRANS_*` constant
+      def transaction_status = @monitor.synchronize { @conn.transaction_status }
+
+      # Runs the block in one transaction, joining one the calling thread already holds.
+      #
+      # @yield the writes to commit together; an exception rolls the outermost one back
+      # @return [Object] the block's own value
+      def transaction(&block)
+        @monitor.synchronize do
+          next yield if @conn.transaction_status != PG::PQTRANS_IDLE
+
+          @conn.transaction(&block)
+        end
+      end
+
+      # Reports the server process id serving the connection.
+      #
+      # @return [Integer] the backend pid
+      def backend_pid = @monitor.synchronize { @conn.backend_pid }
+
+      # Quotes an identifier; needs no connection round trip.
+      #
+      # @param name [String, Symbol] the identifier
+      # @return [String] the double-quoted identifier
+      def quote_ident(name) = PG::Connection.quote_ident(name.to_s)
+
+      # Reports whether the underlying socket is closed or broken.
+      #
+      # @return [Boolean] true when the connection cannot run statements
+      def dead? = @monitor.synchronize { @conn.finished? || @conn.status != PG::CONNECTION_OK }
+
+      # Replaces the connection when it is dead; a no-op when another caller already did.
+      #
+      # @return [void]
+      # @raise [Runtime::WiringError] if the new connection is refused
+      def reconnect!
+        @monitor.synchronize do
+          next unless dead?
+
+          @conn.close unless @conn.finished?
+          @conn = @connector.connect_for(@name, @settings)
+        end
+      end
+
+      # Detaches this handle's socket from the parent's session in a forked child: the child's
+      # fd is repointed at the null device, so nothing the child's copy of the connection writes
+      # (statements, Terminate) reaches the parent's server session. Takes no lock, since the
+      # child holds none of the parent's monitors.
+      #
+      # @return [void]
+      def disown!
+        return if @conn.finished?
+
+        IO.for_fd(@conn.socket, autoclose: false).reopen(File::NULL, "r+")
+      rescue StandardError
+        nil
+      end
+
+      # Closes the underlying connection.
+      #
+      # @return [void]
+      def close = @monitor.synchronize { @conn.close unless @conn.finished? }
+    end
+  end
+end

data/lib/hecks/adapters/driven/postgres.rb

@@ -11,6 +11,7 @@ require_relative "../../runtime/errors"
 require_relative "../../runtime/event"
 require_relative "postgres/outbox"
 require_relative "postgres/reconnect"
+require_relative "postgres/shared_connection"
 require_relative "../../runtime/instance"
 
 module Hecks
@@ -79,7 +80,8 @@ module Hecks
               "cannot bind Postgres at #{declared} for #{name}: #{e.message.strip}"
       end
 
-      # Connects and creates the aggregate, journal, event, saga and outbox tables if absent.
+      # Joins the process's shared connection for the declared database and schema, then
+      # creates the aggregate, journal, event, saga and outbox tables if absent.
       #
       # @param aggregate [Bluebook::Aggregate] the aggregate whose table this adapter owns
       # @param settings [Hash{Symbol, String => Object}] world settings for the binding:
@@ -93,7 +95,7 @@ module Hecks
       def initialize(aggregate:, settings: {}, root: nil)
         @aggregate = aggregate
         @settings  = settings
-        @db = self.class.connect_for(aggregate.name, settings)
+        @db = PostgresSharedConnection.for(aggregate.name, settings, connector: self.class)
         # Scopes saga rows; falls back to the aggregate's storage name when
         # settings gives no domain (e.g. a directly-instantiated adapter).
         @domain = (

data/lib/hecks/adapters/driven/prism.rb

@@ -1,3 +1,4 @@
+require "monitor"
 require "prism"
 require_relative "../../bluebook/expression/canonical_form"
 
@@ -14,6 +15,16 @@ module Hecks
       # rubocop:disable-next Style/MutableConstant
       TREES = {}
 
+      # The first block node starting on each line, per parsed tree (by identity), built by one
+      # walk of the tree the first time a block in its file is looked up. Dropped with its tree
+      # by #forget/#forget_all.
+      BLOCKS_BY_LINE = {}.compare_by_identity
+
+      # Guards `TREES` and `BLOCKS_BY_LINE` together, so a parse or an index build never
+      # interleaves with a `forget` that drops the same tree. Reentrant: `block_node_at`
+      # calls `tree_for` under it.
+      LOCK = Monitor.new
+
       module_function
 
       # Recovers a block's body as canonical source text.
@@ -47,14 +58,25 @@ module Hecks
       # @return [Prism::BlockNode, nil] the first block node found starting on `line`, or nil
       #   if none does
       def block_node_at(file, line)
-        found = nil
-        walk(tree_for(file)) do |node|
+        LOCK.synchronize do
+          tree = tree_for(file)
+          BLOCKS_BY_LINE[tree] ||= blocks_by_line(tree)
+          BLOCKS_BY_LINE[tree][line]
+        end
+      end
+
+      # Indexes a tree's block nodes by the line they start on, keeping the first in walk order.
+      #
+      # @param tree [Prism::ProgramNode] a parsed file's root node
+      # @return [Hash{Integer => Prism::BlockNode}] block node by 1-based start line
+      def blocks_by_line(tree)
+        index = {}
+        walk(tree) do |node|
           next unless node.is_a?(::Prism::BlockNode)
-          next unless node.location.start_line == line
 
-          found ||= node
+          index[node.location.start_line] ||= node
         end
-        found
+        index
       end
 
       # Parses a file with `prism`, caching the result for the life of the process.
@@ -65,7 +87,7 @@ module Hecks
         # ::Prism.parse_file reads the file at the C-extension level, bypassing
         # Ruby's File/IO layer — invisible to tools that virtualize the filesystem
         # there (e.g. tebako's memfs). Read through File.read first so they intercept it.
-        TREES[file] ||= ::Prism.parse(File.read(file)).value
+        LOCK.synchronize { TREES[file] ||= ::Prism.parse(File.read(file)).value }
       end
 
       # Drops one file from the process-wide parse cache, for a caller (`Hecks::Codemod`)
@@ -74,12 +96,23 @@ module Hecks
       # @param file [String] the file path to drop from the cache
       # @return [Prism::ProgramNode, nil] the cached tree that was removed, or nil if
       #   nothing was cached for `file`
-      def forget(file) = TREES.delete(file)
+      def forget(file)
+        LOCK.synchronize do
+          tree = TREES.delete(file)
+          BLOCKS_BY_LINE.delete(tree)
+          tree
+        end
+      end
 
       # Drops every cached parse tree.
       #
       # @return [Hash] the now-empty cache
-      def forget_all = TREES.clear
+      def forget_all
+        LOCK.synchronize do
+          BLOCKS_BY_LINE.clear
+          TREES.clear
+        end
+      end
 
       # Visits `node` and every descendant depth-first, calling `visit` on each.
       #

data/lib/hecks/adapters/driven/tenant_provisioner.rb

@@ -5,8 +5,21 @@ require "fileutils"
 module Hecks
   module Adapters
     # The imperative half of tenant provisioning, behind `Deploy::Tenant.port
-    # "TenantProvisioning"`; booting the domain and its capability gate stay in bin/project_tenant.
+    # "TenantProvisioning"`, for `Tenant.Provision` and for hecks deploy provision; booting the
+    # domain and its capability gate stay in hecks deploy provision.
     class TenantProvisioner
+      # Raised when a value is outside its allow-list or the overlay path leaves `environments/`.
+      class Refused < ArgumentError; end
+
+      # Each argument's allow-list. `\A...\z` anchors: `$` would let a newline end the value early.
+      IDENTIFIER = /\A[a-z][a-z0-9_]*\z/
+      LABEL      = /\A[A-Za-z0-9][A-Za-z0-9_ .:-]*\z/
+      CONSTANT   = /\A[A-Z][A-Za-z0-9]*\z/
+      CONNECTION = /\A[^\x00-\x20\x7f]+\z/
+
+      RULES = { slug: IDENTIFIER, schema: IDENTIFIER, domain: LABEL, realm: LABEL,
+                database: CONNECTION, adapter: CONSTANT }.freeze
+
       # Accepts the arguments every driven adapter is built with and keeps none of them.
       #
       # @param aggregate [Object, nil] unused
@@ -14,30 +27,74 @@ module Hecks
       # @param root [String, nil] unused
       def initialize(aggregate: nil, settings: {}, root: nil); end
 
-      # Writes the tenant's environment overlay file under its domain directory.
+      # Writes the tenant's environment overlay under `<directory>/environments/`.
       #
-      # `directory:` must be passed explicitly — a domain's declared name is not a
-      # filesystem path. Each argument arrives either bare or wrapped as `{ value: }`.
+      # Each argument arrives bare or wrapped as `{ value: }`; the record's other fields are
+      # ignored. Values are allow-listed and written as Ruby string literals.
       #
       # @param slug [String, Hash] names the overlay file
-      # @param directory [String, Hash] the domain's own directory on disk
-      # @return [Hash{Symbol => Object}] `:slug`, `:domain`, `:realm` and `:schema`, as given
-      def provision(slug:, domain:, realm:, schema:, database:, adapter:, directory:)
-        domain_directory = File.expand_path(directory[:value] || directory)
+      # @param directory [String, Hash] the domain's own directory on disk (not its declared name)
+      # @param adapter [String, Hash, nil] the adapter the overlay binds; PostgresEra when none
+      # @return [Hash{Symbol => Object}] `:slug`, `:domain`, `:realm`, `:schema` and `:output`
+      # @raise [Refused] when a value is outside its allow-list or the path leaves `environments/`
+      def write_overlay(slug:, domain:, realm:, schema:, database:, directory:, adapter: nil, **)
+        values = { slug: unwrap(slug), domain: unwrap(domain), realm: unwrap(realm),
+                   schema: unwrap(schema), database: unwrap(database),
+                   adapter: adapter_name(adapter) }
+        values.each { |name, value| check(name, value) }
 
-        overlay_path = File.join(domain_directory, "environments", "#{slug[:value] || slug}.world")
+        overlay_path = overlay_path_for(unwrap(directory), values[:slug])
+        refuse_missing_directory(unwrap(directory))
         FileUtils.mkdir_p(File.dirname(overlay_path))
-        File.write(overlay_path, <<~WORLD)
-          Hecks.world "#{domain[:value] || domain}" do
-            realm "#{realm[:value] || realm}"
-            persisted_by("#{adapter[:value] || adapter}") do
-              database "#{database[:value] || database}"
-              schema   "#{schema[:value] || schema}"
+        File.write(overlay_path, render(values))
+
+        { slug: slug, domain: domain, realm: realm, schema: schema,
+          output: { value: "wrote #{overlay_path}\n" } }
+      end
+
+      private
+
+      # A tenant overlay belongs to a domain that exists: a missing directory is a mistyped path,
+      # not a place to create.
+      def refuse_missing_directory(directory)
+        return if File.directory?(directory.to_s)
+
+        raise Refused, "directory #{directory.to_s.inspect} is not an existing domain directory"
+      end
+
+      def render(values)
+        <<~WORLD
+          Hecks.world #{values[:domain].inspect} do
+            realm #{values[:realm].inspect}
+            persisted_by(#{values[:adapter].inspect}) do
+              database #{values[:database].inspect}
+              schema   #{values[:schema].inspect}
             end
           end
         WORLD
+      end
+
+      def unwrap(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+
+      def check(name, value)
+        return if value.is_a?(String) && RULES.fetch(name).match?(value)
+
+        raise Refused, "#{name} #{value.inspect} is not an accepted #{name}"
+      end
+
+      def overlay_path_for(directory, slug)
+        raise Refused, "directory is required" unless directory.is_a?(String) && !directory.empty?
+
+        environments = File.join(File.expand_path(directory), "environments")
+        path = File.expand_path("#{slug}.world", environments)
+        return path if path.start_with?("#{environments}#{File::SEPARATOR}")
+
+        raise Refused, "overlay path #{path} is outside #{environments}"
+      end
 
-        { slug: slug, domain: domain, realm: realm, schema: schema }
+      def adapter_name(adapter)
+        name = unwrap(adapter)
+        name.nil? || name.to_s.empty? ? "PostgresEra" : name
       end
     end
   end

data/lib/hecks/behaviors/expectations.rb

@@ -81,7 +81,7 @@ module Hecks
       #   Memory-only-guarded runtime
       # @raise [Malformed] if any aggregate is bound to a non-Memory adapter
       def boot_and_guard(files)
-        runtime = Hecks::Runtime::Loader.boot_files(files, install_facade: false)
+        runtime = Hecks::Runtime::Loader.boot_files(files, install_doors: false)
         guard_memory_only!(runtime)
         runtime
       end

data/lib/hecks/behaviors.rb

@@ -2,7 +2,7 @@ require_relative "behaviors/dsl"
 require_relative "behaviors/expectations"
 require_relative "behaviors/runner"
 
-# The `.behaviors` toolkit driven by `bin/behaviors` and `hecks/behaviors/rspec`.
+# The `.behaviors` toolkit driven by `hecks run_behaviors` and `hecks/behaviors/rspec`.
 # Opt-in: not required by lib/hecks.rb, like `Fuzzing`.
 # lib/hecks/fuzzing.rb, the shape this file mirrors) is opt-in too.
 module Hecks