hecks 2.5.1 → 2.7.0

data/lib/hecks/embryonaut_bluebook/vendor_cli.rb

@@ -0,0 +1,88 @@
+require "optparse"
+require_relative "vendor"
+
+module Hecks
+  module EmbryonautBluebook
+    # The command line behind `bin/vendor_bluebook`.
+    #
+    # It lives in the gem, not in a script, so a consuming project reaches it
+    # through its own bundle without a copy of the script:
+    #
+    #     bundle exec ruby -rhecks \
+    #       -e 'exit Hecks::EmbryonautBluebook::VendorCli.run(ARGV)' payments@1.2.0
+    #
+    # ## Usage
+    #
+    #     vendor_bluebook <package>[@<version-or-commit>] [--from <path>] [--root <path>]
+    #
+    # `--from` defaults to `$EMBRYONAUT_BLUEBOOKS_SRC` and `--root` to the current
+    # directory. `ALLOW_DOWNGRADE=1` in the environment permits a release older
+    # than the vendored one.
+    module VendorCli
+      USAGE = "usage: vendor_bluebook <package>[@<version-or-commit>] [--from PATH] [--root PATH]".freeze
+
+      # Runs the command and reports on the given streams.
+      #
+      # @param argv [Array<String>] the command-line arguments
+      # @param env [Hash{String => String}] the environment
+      # @param out [IO] where the report goes
+      # @param err [IO] where a refusal goes
+      # @param root [String] the default project root
+      # @return [Integer] the exit status, 0 when the package was vendored
+      def self.run(argv, env: ENV, out: $stdout, err: $stderr, root: Dir.pwd)
+        options = { from: env["EMBRYONAUT_BLUEBOOKS_SRC"], root: root }
+        spec = parse(argv, options)
+        return usage(err) unless spec && options[:from]
+
+        name, _, ref = spec.partition("@")
+        result = Vendor.new(name, from: options[:from], root: options[:root], ref: ref.empty? ? nil : ref,
+                                  allow_downgrade: env["ALLOW_DOWNGRADE"] == "1").call
+        report(result, options[:from], out)
+        0
+      rescue Vendoring::Error, OptionParser::ParseError => e
+        err.puts(e.message)
+        1
+      end
+
+      # Reads the options into a hash and picks out the package argument.
+      #
+      # @param argv [Array<String>] the command-line arguments
+      # @param options [Hash{Symbol => String}] receives `:from` and `:root` when given
+      # @return [String, nil] the one positional argument, nil unless exactly one was given
+      def self.parse(argv, options)
+        parser = OptionParser.new
+        parser.on("--from PATH") { |path| options[:from] = path }
+        parser.on("--root PATH") { |path| options[:root] = path }
+        rest = parser.parse(argv)
+        rest.first if rest.length == 1
+      end
+
+      def self.usage(err)
+        err.puts(USAGE)
+        2
+      end
+
+      def self.report(result, from, out)
+        label = result.release? ? "#{result.version} (#{result.tag}, #{result.commit[0, 7]})" : result.commit[0, 12]
+        out.puts("Vendored embryonaut_bluebooks/#{result.package} #{label} from #{from} into #{result.dir}")
+        out.puts(shape_line(result))
+      end
+
+      # The shape label tells a re-vendor that only moved the pin apart from one
+      # that will mint a new era on the next deploy.
+      def self.shape_line(result)
+        now = result.shape.join(" ")
+        if result.previous_shape.nil?
+          "Shape: #{now} (no earlier vendored copy to compare against)"
+        elsif result.shape_changed?
+          "SHAPE CHANGED: the next deploy mints a new era; add its translation edge first.\n  " \
+            "before: #{result.previous_shape.join(' ')}\n  after:  #{now}"
+        else
+          "Shape unchanged: #{now}. No new era on deploy."
+        end
+      end
+
+      private_class_method :parse, :usage, :report, :shape_line
+    end
+  end
+end

data/lib/hecks/embryonaut_bluebook.rb

@@ -13,10 +13,10 @@ module Hecks
   #
   # This module and its `uses_embryonaut_bluebook`
   # DSL word (hecksagon_builder.rb) were built on a prior commit of this
-  # repo (933d1dd), vendored out to a real consumer (lifeadelics/domain,
+  # repo (933d1dd), vendored out to a real consumer (a client site's domain,
   # for embryonaut_bluebooks/payments), and then lost from this repo's own
   # reachable history — a hard reset or rebase left no branch containing
-  # that commit. The lifeadelics vendor snapshot (a `git archive` of that
+  # that commit. The consumer's vendor snapshot (a `git archive` of that
   # commit, committed into their repo) was the only surviving copy; this
   # file is ported forward from it, checked against current `main`'s own
   # conventions rather than copied wholesale, since the two trees had
@@ -64,7 +64,18 @@ module Hecks
   # => "Payments"), not a separate ledger. A vendored package's directory
   # name and its declared `Hecks.bluebook` name are the one convention
   # this reuses from Framework rather than reinventing.
+  #
+  # ## Vendoring
+  #
+  # `vendor!` is the other direction: it pins a package from a local checkout
+  # of the registry into a consuming project's own `vendor/` tree, and is the
+  # one implementation behind `bin/vendor_bluebook` (see Vendoring and Vendor).
   module EmbryonautBluebook
+    autoload :Lock, File.join(__dir__, "embryonaut_bluebook/lock")
+    autoload :Shape, File.join(__dir__, "embryonaut_bluebook/shape")
+    autoload :Vendor, File.join(__dir__, "embryonaut_bluebook/vendor")
+    autoload :VendorCli, File.join(__dir__, "embryonaut_bluebook/vendor_cli")
+
     # Loads a vendored embryonaut bluebook package's `.bluebook` files, once
     # per registry.
     #
@@ -89,10 +100,25 @@ module Hecks
       if files.empty?
         raise Runtime::WiringError,
               "no vendored embryonaut bluebook named #{name.inspect} at #{dir} — " \
-              "run bin/vendor_embryonaut_bluebooks #{name}"
+              "vendor it with bin/vendor_bluebook #{name}"
       end
 
       files.each { |file| Kernel.load(file) }
     end
+
+    # Pins one package of the registry into a project's `vendor/` tree.
+    #
+    # @param name [String, Symbol] the package's directory name, such as `"payments"`
+    # @param from [String] path of a local checkout of the registry repository
+    # @param ref [String, nil] a release version (`"1.2.0"`), a release tag name, any
+    #   commit-ish, or nil for the newest release
+    # @param root [String] the consuming project's root
+    # @param allow_downgrade [Boolean] whether a release older than the vendored one is allowed
+    # @return [Vendor::Result] the commit, version and storage shape now vendored
+    # @raise [Vendoring::Error] if the source, release or files are unusable, or a
+    #   version-policy refusal applies (see Vendor)
+    def self.vendor!(name, from:, root:, ref: nil, allow_downgrade: false)
+      Vendor.new(name, from: from, root: root, ref: ref, allow_downgrade: allow_downgrade).call
+    end
   end
 end

data/lib/hecks/forms/value_object_shape.rb

@@ -2,7 +2,7 @@ module Hecks
   module Forms
     # The value-object classification every consumer of a resolved VO
     # shape needs, spelled once — `field_shape.rb` (a command's own
-    # form), `ui_schema.rb` (embryonaut_console's table/detail-panel
+    # form), `ui_schema.rb` (the console app's table/detail-panel
     # renderer, a separate app, not this repo), and
     # `adapters/driven/sql_query_builder.rb` (a query's own ORDER BY/
     # where compiler) each grew their own copy of "is this VO money-

data/lib/hecks/framework/bluebook/console_settings.bluebook

@@ -1,5 +1,5 @@
 Hecks.bluebook "ConsoleSettings" do
-  vision "A generic admin console's own curated UI facts — nav, columns, state tones, which rows a detail panel shows — as real dispatched data instead of a hand-rewritten YAML file. A UI opinion the DOMAIN it's pointed at has no way to answer, never a business record; see embryonaut_console's own presentation_config.rb for the fuller story."
+  vision "A generic admin console's own curated UI facts — nav, columns, state tones, which rows a detail panel shows — as real dispatched data instead of a hand-rewritten YAML file. A UI opinion the DOMAIN it's pointed at has no way to answer, never a business record; see the console app's own presentation_config.rb for the fuller story."
   supporting
 
   # A FRAMEWORK MEMBER LIKE IDENTITY/GOVERNANCE — attach with
@@ -7,7 +7,7 @@ Hecks.bluebook "ConsoleSettings" do
   # `.hecksagon`, plus a `Hecks.hecksagon "ConsoleSettings" do ... end`
   # persistence binding (Heki is the common case — a small, local,
   # per-app settings store, no shared database needed). This used to
-  # boot in a SECOND, independent registry (embryonaut_console's own
+  # boot in a SECOND, independent registry (the console app's own
   # console_settings_domain.rb) specifically so no consuming app needed
   # any change at all — that property is real and now given up on
   # purpose, in favor of the one binding mechanism every other
@@ -30,7 +30,7 @@ Hecks.bluebook "ConsoleSettings" do
   # (Overview, below) and every `extra_json`/`identity_extra_json`
   # field throughout this chapter were BOTH originally scoped out on an
   # "confirmed unused in any real presentation.yml" basis that turned
-  # out to be checked against the wrong file — embryonaut_console's own
+  # out to be checked against the wrong file — the console app's own
   # fixture, never this app's actual, live one. Migrating the real file
   # found both very much in use.
 

data/lib/hecks/fuzzing/era_boundary.rb

@@ -82,7 +82,7 @@ module Hecks
           return not_applicable("#{bluebook.name} is bound to #{adapter_name}, not PostgresEra")
         end
 
-        settings = registry.world(bluebook.name)&.for_binding(Hecks::Ports::Persistence::VERB, adapter_name) || {}
+        settings = registry.binding_settings(bluebook.name, Hecks::Ports::Persistence::VERB, adapter_name)
         db = Hecks::Adapters::PostgresEra.connect_for(bluebook.name, settings)
         begin
           lineage = Hecks::Adapters::PostgresEra::Lineage.new(db, bluebook.name)

data/lib/hecks/fuzzing/isolated_boot.rb

@@ -93,13 +93,17 @@ module Hecks
       #   `adapter: :postgres_era`; ignored by every other adapter
       # @param schema [String, nil] the schema name, required only for
       #   `adapter: :postgres_era`; ignored by every other adapter
+      # @param scratch [Hash{Symbol => String}] `:database` and/or `:schema` for
+      #   `adapter: :postgres` to use instead of the shared fuzz scratch schema, so a caller
+      #   such as `bin/bench` never drops the schema a concurrent `bin/fuzz` is using;
+      #   ignored by every other adapter
       # @yield [String] the freshly rebound copy's root directory, ready to boot
       # @yieldreturn [Object] anything; becomes this method's own return value
       # @return [Object] whatever the given block returns
       # @raise [ArgumentError] if `adapter` is not `:memory`, `:sqlite`, `:postgres`, or
       #   `:postgres_era`, or if `adapter: :postgres_era` is given without both
       #   `database:` and `schema:`
-      def call(domain_path, adapter: :memory, database: nil, schema: nil)
+      def call(domain_path, adapter: :memory, database: nil, schema: nil, scratch: {})
         Dir.mktmpdir("hecks-fuzz") do |tmp|
           copy = File.join(tmp, File.basename(domain_path))
           copy_dereferencing(domain_path, copy)
@@ -107,7 +111,7 @@ module Hecks
           case adapter
           when :memory       then rebind_to_memory!(copy)
           when :sqlite       then rebind_to_sqlite!(copy)
-          when :postgres     then rebind_to_postgres!(copy)
+          when :postgres     then rebind_to_postgres!(copy, **scratch)
           when :postgres_era then rebind_to_postgres_era!(copy, database: database, schema: schema)
           else raise ArgumentError,
                      "unknown fuzz adapter #{adapter.inspect} — :memory, :sqlite, :postgres, or :postgres_era"
@@ -196,8 +200,8 @@ module Hecks
         end
       end
 
-      # Rewrites every `.hecksagon` in the copy to bind through Memory and drops its
-      # `.world` files, so the boot needs no settings at all.
+      # Rewrites every `.hecksagon` in the copy to bind through Memory and replaces its
+      # `.world` files with a `default_adapter "Memory"` one, so the boot needs no settings.
       #
       # @param copy [String] the isolated copy's root directory
       # @return [void]
@@ -215,8 +219,11 @@ module Hecks
         # `data/<table>.db` under `root:` when unset — the same
         # zero-config default Memory gets from having no `.world` at
         # all), so the simplest correct fix for either target is
-        # dropping `.world` from the copy entirely.
-        Dir.glob(File.join(copy, "**", "*.world")).each { |path| File.delete(path) }
+        # dropping the shipped `.world` from the copy. What replaces it is
+        # only a `default_adapter`, so an aggregate the hecksagon leaves
+        # unbound (the real world's `default_adapter` bound it) still lands on
+        # this mode's adapter — see `write_default_worlds!`.
+        write_default_worlds!(copy, "Memory")
       end
 
       # Same dance as memory, one adapter over — `Adapters::Sqlite#
@@ -233,7 +240,7 @@ module Hecks
       def rebind_to_sqlite!(copy)
         rewrite_bindings!(copy, "SqlitePersistence")
         strip_translations!(copy)
-        Dir.glob(File.join(copy, "**", "*.world")).each { |path| File.delete(path) }
+        write_default_worlds!(copy, "SqlitePersistence")
       end
 
       # **The expensive one** — Postgres has no zero-config default the way
@@ -262,15 +269,20 @@ module Hecks
       FUZZ_POSTGRES_SCHEMA   = "hecks_fuzz".freeze
 
       # Rewrites every `.hecksagon` in the copy to bind through Postgres, against the
-      # shared `FUZZ_POSTGRES_DATABASE`/`FUZZ_POSTGRES_SCHEMA` scratch schema.
+      # shared `FUZZ_POSTGRES_DATABASE`/`FUZZ_POSTGRES_SCHEMA` scratch schema unless the
+      # caller names its own, which lets `bin/bench` run without touching the fuzzer's.
       #
       # @param copy [String] the isolated copy's root directory
+      # @param database [String, nil] the scratch database, `FUZZ_POSTGRES_DATABASE` when nil
+      # @param schema [String, nil] the scratch schema, `FUZZ_POSTGRES_SCHEMA` when nil
       # @return [void]
-      def rebind_to_postgres!(copy)
+      def rebind_to_postgres!(copy, database: nil, schema: nil)
         require "pg"
+        database ||= FUZZ_POSTGRES_DATABASE
+        schema   ||= FUZZ_POSTGRES_SCHEMA
         rewrite_bindings!(copy, "Postgres")
         strip_translations!(copy)
-        ensure_fuzz_schema!
+        ensure_fuzz_schema!(database, schema)
 
         # One `.world` per directory a `.hecksagon` actually lives in, not
         # one at `copy`'s own root — `Folder#load_domain` resolves a
@@ -278,35 +290,20 @@ module Hecks
         # recursively (`Folder#load_each`); a domain can hold several
         # `Hecks.hecksagon "<Name>" do ... end` sibling blocks in that one
         # file (banking.hecksagon declares "Banking", "Governance", and
-        # "Identity" together), so every name found in one `.hecksagon`
-        # file gets bundled into one `.world` written beside it, not
-        # scattered by name.
-        Dir.glob(File.join(copy, "**", "*.hecksagon")).each do |hecksagon_path|
-          names = File.read(hecksagon_path).scan(/Hecks\.hecksagon\s+"([^"]+)"/).flatten.uniq
-          next if names.empty?
-
-          world_path = File.join(File.dirname(hecksagon_path), "hecks_fuzz_postgres.world")
-          File.write(world_path, names.map do |name|
-            <<~WORLD
-              Hecks.world "#{name}" do
-                persisted_by("Postgres") do
-                  database "#{FUZZ_POSTGRES_DATABASE}"
-                  schema "#{FUZZ_POSTGRES_SCHEMA}"
-                end
+        # "Identity" together), so every name found in one directory
+        # is bundled into one `.world` written there, not scattered by name.
+        write_worlds!(copy, "hecks_fuzz_postgres.world") do |name|
+          <<~WORLD
+            Hecks.world "#{name}" do
+              default_adapter "Postgres"
+              persisted_by("Postgres") do
+                database "#{database}"
+                schema "#{schema}"
               end
-            WORLD
-          end.join("\n"))
-        end
-
-        # Any pre-existing `.world` this copy shipped with (a real
-        # deployment's own connection string) is now redundant with — and
-        # would conflict with, `Registry#add_world`'s own header on
-        # loading the same domain name twice — the fresh one just
-        # written above, so it goes the same way `rebind_to_memory!`
-        # already sends every `.world` in a Memory-mode boot.
-        Dir.glob(File.join(copy, "**", "*.world")).each do |path|
-          File.delete(path) unless File.basename(path) == "hecks_fuzz_postgres.world"
+            end
+          WORLD
         end
+        write_unbound_chapter_worlds!(copy)
       end
 
       # Admin connection lives outside the tmp copy entirely — same as
@@ -318,8 +315,10 @@ module Hecks
       # recreated on every call, which is what actually isolates one
       # ephemeral boot's data from the next.
       #
+      # @param database [String] the scratch database to create if missing
+      # @param schema [String] the schema to drop and recreate inside it
       # @return [void]
-      def ensure_fuzz_schema!
+      def ensure_fuzz_schema!(database = FUZZ_POSTGRES_DATABASE, schema = FUZZ_POSTGRES_SCHEMA)
         # `Adapters::Postgres#initialize` opens one real `PG::Connection`
         # per aggregate and never explicitly closes it — fine for a
         # process that boots once and runs, exactly what every other
@@ -342,17 +341,18 @@ module Hecks
         # something to route around by connecting less carefully.
         GC.start
 
-        unless @fuzz_database_ready
+        @fuzz_databases_ready ||= {}
+        unless @fuzz_databases_ready[database]
           admin = PG.connect(dbname: "postgres")
           exists = admin.exec_params(
-            "SELECT 1 FROM pg_database WHERE datname = $1", [FUZZ_POSTGRES_DATABASE]
+            "SELECT 1 FROM pg_database WHERE datname = $1", [database]
           ).ntuples.positive?
-          admin.exec(%(CREATE DATABASE "#{FUZZ_POSTGRES_DATABASE}")) unless exists
+          admin.exec(%(CREATE DATABASE "#{database}")) unless exists
           admin.close
-          @fuzz_database_ready = true
+          @fuzz_databases_ready[database] = true
         end
 
-        db = PG.connect(dbname: FUZZ_POSTGRES_DATABASE)
+        db = PG.connect(dbname: database)
         # **Quiet on purpose** — same as `Adapters::Postgres.connect_for`'s
         # own `SET client_min_messages`: a `DROP SCHEMA ... CASCADE` that
         # actually has something to drop (every boot after the first)
@@ -361,7 +361,7 @@ module Hecks
         # output under a wall of "drop cascades to table ..." on every
         # single ephemeral boot.
         db.exec("SET client_min_messages = warning")
-        quoted = db.quote_ident(FUZZ_POSTGRES_SCHEMA)
+        quoted = db.quote_ident(schema)
         db.exec("DROP SCHEMA IF EXISTS #{quoted} CASCADE")
         db.exec("CREATE SCHEMA #{quoted}")
         db.close
@@ -416,9 +416,9 @@ module Hecks
         ensure_postgres_era_schema!(database: database, schema: schema)
 
         # Same one-`.world`-per-`.hecksagon`-directory shape `rebind_to_
-        # postgres!` already uses, for the identical reason (`Folder#
-        # load_domain` globs `*.world` non-recursively) — see that
-        # method's own comment on `world_path` above. `PostgresEra`
+        # postgres!` uses, for the identical reason (`Folder#
+        # load_domain` globs `*.world` non-recursively) — see
+        # `write_worlds!`. `PostgresEra`
         # additionally takes `schema:` (postgres_era.rb's own "shared-
         # instance isolation" comment): the caller-supplied throwaway
         # schema is what actually isolates this one ephemeral boot from
@@ -444,36 +444,103 @@ module Hecks
         # database it is about to throw away; the one-line warning
         # PostgresEra prints per boot under the opt-in is the honest
         # price. Inert on a machine whose ambient user is ordinary.
-        # One world file per directory, every hecksagon name in that
-        # directory — not one write per *.hecksagon file. context_map.hecksagon
-        # sits beside the domain file; a second File.write to the same
-        # hecks_fuzz_postgres_era.world would drop the first file's names
-        # (found live: ConcurrentDispatchUnboundFixture + Governance).
-        worlds_by_dir = Hash.new { |h, k| h[k] = [] }
+        write_worlds!(copy, "hecks_fuzz_postgres_era.world") do |name|
+          <<~WORLD
+            Hecks.world "#{name}" do
+              default_adapter "PostgresEra"
+              persisted_by("PostgresEra") do
+                database "#{database}"
+                schema "#{schema}"
+                allow_superuser true
+              end
+            end
+          WORLD
+        end
+        write_unbound_chapter_worlds!(copy)
+      end
+
+      # Replaces every `.world` in the copy with one that declares only `default_adapter`,
+      # so the copy needs no settings and an aggregate its hecksagon leaves unbound
+      # (a chapter whose real world bound it through `default_adapter`) persists through
+      # `adapter_name` like every bound one.
+      #
+      # @param copy [String] the isolated copy's root directory
+      # @param adapter_name [String] the persistence adapter every unbound aggregate falls
+      #   back to, such as `"Memory"` or `"SqlitePersistence"`
+      # @return [void]
+      def write_default_worlds!(copy, adapter_name)
+        write_worlds!(copy, "hecks_fuzz_default.world") do |name|
+          <<~WORLD
+            Hecks.world "#{name}" do
+              default_adapter "#{adapter_name}"
+            end
+          WORLD
+        end
+      end
+
+      # Gives every chapter no hecksagon names a world of its own that falls back to Memory.
+      #
+      # A chapter with a bluebook and no hecksagon block (the framework's Privacy) has no
+      # bind, and the worlds `write_worlds!` wrote declare a `default_adapter` that needs a
+      # `database`: left alone, the chapter resolves that adapter through the project's
+      # world with no connection and the boot refuses (`WiringError ... needs a database
+      # connection`). It persisted through Memory before those worlds carried a
+      # `default_adapter`, and a chapter's own world's default wins over the project's, so
+      # this keeps it there.
+      #
+      # @param copy [String] the isolated copy's root directory
+      # @return [void]
+      def write_unbound_chapter_worlds!(copy)
+        named = Dir.glob(File.join(copy, "**", "*.hecksagon")).flat_map do |path|
+          File.read(path).scan(/Hecks\.hecksagon\s+"([^"]+)"/).flatten
+        end
+        bluebooks = Dir.glob(File.join(copy, "**", "*.bluebook")).group_by { |path| File.dirname(path) }
+        bluebooks.each do |dir, files|
+          unbound = files.flat_map { |path| File.read(path).scan(/Hecks\.bluebook[\s(]+"([^"]+)"/).flatten }
+                         .uniq - named
+          named.concat(unbound)
+          next if unbound.empty?
+
+          worlds = unbound.map { |name| %(Hecks.world "#{name}" do\n  default_adapter "Memory"\nend\n) }
+          File.write(File.join(dir, "hecks_fuzz_unbound.world"), worlds.join("\n"))
+        end
+      end
+
+      # Writes one `.world` file per directory that holds a `.hecksagon`, naming every
+      # `Hecks.hecksagon` block found in that directory, and deletes every other `.world`
+      # in the copy.
+      #
+      # One world file per directory, every hecksagon name in that directory — never one
+      # write per `*.hecksagon` file. A domain's `context_map.hecksagon` sits beside its
+      # main hecksagon (the `qa` domain declares Governance in one and QualityControl in
+      # the other), and a second `File.write` to the same world path would drop the first
+      # file's names, leaving that domain bound to Postgres with no `database` to open.
+      #
+      # Any `.world` the copy shipped with (a real deployment's own connection string) is
+      # redundant with, and would conflict with (`Registry#add_world`'s own header, on
+      # loading the same domain name twice), the fresh one written here, so it goes the same
+      # way `rebind_to_memory!` sends every `.world` in a Memory-mode boot.
+      #
+      # @param copy [String] the isolated copy's root directory
+      # @param world_file [String] the basename of the world file written in each directory
+      # @yield [name] builds the world text for one hecksagon name
+      # @yieldparam name [String] a domain name a `Hecks.hecksagon` block in the directory declares
+      # @yieldreturn [String] the `Hecks.world` block for that name
+      # @return [void]
+      def write_worlds!(copy, world_file, &world_for)
+        names_by_dir = Hash.new { |hash, dir| hash[dir] = [] }
         Dir.glob(File.join(copy, "**", "*.hecksagon")).each do |hecksagon_path|
           names = File.read(hecksagon_path).scan(/Hecks\.hecksagon\s+"([^"]+)"/).flatten
-          worlds_by_dir[File.dirname(hecksagon_path)].concat(names)
+          names_by_dir[File.dirname(hecksagon_path)].concat(names)
         end
-        worlds_by_dir.each do |dir, names|
-          names = names.uniq
+        names_by_dir.each do |dir, names|
           next if names.empty?
 
-          world_path = File.join(dir, "hecks_fuzz_postgres_era.world")
-          File.write(world_path, names.map do |name|
-            <<~WORLD
-              Hecks.world "#{name}" do
-                persisted_by("PostgresEra") do
-                  database "#{database}"
-                  schema "#{schema}"
-                  allow_superuser true
-                end
-              end
-            WORLD
-          end.join("\n"))
+          File.write(File.join(dir, world_file), names.uniq.map(&world_for).join("\n"))
         end
 
         Dir.glob(File.join(copy, "**", "*.world")).each do |path|
-          File.delete(path) unless File.basename(path) == "hecks_fuzz_postgres_era.world"
+          File.delete(path) unless File.basename(path) == world_file
         end
       end
 

data/lib/hecks/language/world/world.bluebook

@@ -4,8 +4,10 @@ Hecks.bluebook "World" do
 
     identified_by WorldName, as: :domain
 
-    attribute :realm,  Realm
-    attribute :latest, Latest
+    attribute :realm,            Realm
+    attribute :latest,           Latest
+    attribute :default_database, DefaultDatabase
+    attribute :default_adapter,  DefaultAdapter
 
     value_object "WorldName" do
       attribute :value, String
@@ -22,6 +24,22 @@ Hecks.bluebook "World" do
       invariant("a latest version says something") { !value.to_s.empty? }
     end
 
+    # The connection every chapter's database-taking persistence adapter
+    # uses unless that chapter's own world says otherwise — a world's
+    # per-chapter `persisted_by ... database` block, written once.
+    value_object "DefaultDatabase" do
+      attribute :value, String
+      invariant("a default database says something") { !value.to_s.empty? }
+    end
+
+    # The persistence adapter every aggregate binds to unless its own
+    # chapter's hecksagon binds it — between an explicit bind and the
+    # framework's in-memory fallback.
+    value_object "DefaultAdapter" do
+      attribute :value, String
+      invariant("a default adapter names an adapter") { !value.to_s.empty? }
+    end
+
     command "Declare" do
       role "Deployment"
       goal "Open a world for a domain"
@@ -29,10 +47,14 @@ Hecks.bluebook "World" do
       attribute :domain, WorldName
       attribute :realm,  Realm, optional: true
       attribute :latest, Latest, optional: true
+      attribute :default_database, DefaultDatabase, optional: true
+      attribute :default_adapter,  DefaultAdapter,  optional: true
 
       sets :domain
       sets :realm
       sets :latest
+      sets :default_database
+      sets :default_adapter
 
       emits "WorldDeclared"
     end
@@ -55,6 +77,12 @@ Hecks.bluebook "World" do
       member word: "world",           context: "File",     body: "keywords", inner: "World",          opens: "World",          fills: ""
       member word: "realm",           context: "World",     body: "none", inner: "", opens: "", fills: "realm", calls: "realm_impl"
       member word: "latest",          context: "World",     body: "none", inner: "", opens: "", fills: "latest", calls: "latest_impl"
+      # THE TWO CROSS-CHAPTER DEFAULTS — the same connection string and the
+      # same persistence adapter every chapter of a project repeats, written
+      # once. A chapter's own world (`persisted_by ... database`) and its own
+      # hecksagon bind still win; see docs/implemented/reference/world.md.
+      member word: "default_database", context: "World", body: "none", inner: "", opens: "", fills: "default_database", calls: "default_database_impl"
+      member word: "default_adapter",  context: "World", body: "none", inner: "", opens: "", fills: "default_adapter", calls: "default_adapter_impl"
 
     end
 
@@ -78,6 +106,8 @@ Hecks.bluebook "World" do
       member keyword: "world",           context: "File", at: "1", named: "", kind: "text", required: "true", fills: "domain"
       member keyword: "realm",           context: "World", at: "1", named: "", kind: "text", required: "true", fills: "realm"
       member keyword: "latest",          context: "World", at: "1", named: "", kind: "text", required: "true", fills: "latest"
+      member keyword: "default_database", context: "World", at: "1", named: "", kind: "text", required: "true", fills: "default_database"
+      member keyword: "default_adapter",  context: "World", at: "1", named: "", kind: "text", required: "true", fills: "default_adapter"
 
     end
   end