hecks 3.14.0 → 5.0.0

data/lib/hecks/projections/rust_vocabulary.rb

@@ -1,5 +1,7 @@
+require_relative "../naming"
 require_relative "../projector"
 require_relative "../runtime/refusal_wording"
+require_relative "../vocabulary"
 require_relative "vocabulary"
 require_relative "rust_vocabulary/enum_body"
 require_relative "rust_vocabulary/arguments"
@@ -33,12 +35,20 @@ module Hecks
                                       kind: :order }
       }.freeze
 
-      RUST_KEYWORDS = %w[as async await break const continue crate dyn else enum extern false fn for if impl in let loop
-                         match mod move mut pub ref return self static struct super trait true type unsafe use where
-                         while abstract become box do final macro override priv typeof unsized virtual yield try].freeze
+      # Keywords Rust refuses as a raw identifier, so they cannot take the `r#` escape.
+      NOT_RAW = %w[crate self Self super].freeze
 
       module_function
 
+      # @param name [String] a field's name
+      # @return [String] the Rust field: raw-escaped when a keyword, with a trailing underscore
+      #   when the keyword cannot be raw
+      def field_name(name)
+        return "#{name}_" if NOT_RAW.include?(name)
+
+        Hecks::Vocabulary.fetch("RustReservedWord").include?(name) ? "r##{name}" : name
+      end
+
       def call(bluebook:, options: {}) = render(bluebook)
 
       def render(bluebook)
@@ -121,14 +131,12 @@ module Hecks
       def accessor_name(field) = field == "refusal" ? "refusal_class" : field
 
       def variant_name(row, fields)
-        name = fields.map { |field| pascal(row.fetch(field)) }.join
+        name = fields.map { |field| Naming.pascal(row.fetch(field)) }.join
         raise ArgumentError, "#{name.inspect} is not a Rust variant name" unless name.match?(/\A[A-Z][A-Za-z0-9]*\z/)
 
         name
       end
 
-      def pascal(text) = text.to_s.split("_").map { |part| part[0].to_s.upcase + part[1..].to_s }.join
-
       # Only `\`, `"` and newlines need escaping in the text a vocabulary row holds.
       def rust_string(text)
         escaped = text.to_s.gsub("\\") { "\\\\" }.gsub('"') { "\\\"" }.gsub("\n") { "\\n" }

data/lib/hecks/projections/site/cms_editor/color.rb

@@ -97,12 +97,6 @@ module Hecks
           # @return [Boolean] whether `value` reaches `ratio` on every background
           def reads?(value, against, ratio) = against.all? { |back| contrast(value, back) >= ratio }
 
-          # @param background [String] a fill
-          # @param light [String] a light foreground to try
-          # @param dark [String] a dark foreground to try
-          # @return [String] whichever reads better on `background`
-          def foreground(background, light, dark) = contrast(light, background) >= contrast(dark, background) ? light : dark
-
           # @return [Float] the hue, in degrees, of a colour given by its channels
           def angle(red, green, blue, high, spread)
             degrees = if high == red then ((green - blue) / spread) % 6

data/lib/hecks/projections/site/cms_editor/templates/src/host.ts.tmpl

@@ -23,9 +23,14 @@ export function hostUrl(options: HostOptions = {}): string {
   return (options.url ?? (process.env[EDITOR.hostEnv] || EDITOR.hostDefault)).replace(/\/+$/, "");
 }
 
-/** A client for the domain this editor edits. */
+/**
+ * A client for the domain this editor edits. It reads and writes the stored shape (`bare: false`),
+ * since its forms walk every value object by the schema's own fields.
+ */
 export function hostClient(options: HostOptions = {}): HostClient {
-  return new HostClient({ domain: options.domain ?? SCHEMA.domain, url: hostUrl(options), fetch: options.fetch, timeoutMs: EDITOR.timeoutMs });
+  return new HostClient({
+    domain: options.domain ?? SCHEMA.domain, url: hostUrl(options), fetch: options.fetch, timeoutMs: EDITOR.timeoutMs, bare: false,
+  });
 }
 
 /**

data/lib/hecks/projections/statements/actions.rb

@@ -0,0 +1,99 @@
+require_relative "../plain_english"
+
+module Hecks
+  module Projections
+    module Statements
+      # The statements a holder's lifecycle and commands carry: where it starts, what moves it
+      # between states, who does each command, and every rule a command checks before and after.
+      # Rule text is the author's own; only the command's name is turned into words around it.
+      #
+      #   Actions.rules(order) # => ["Adding a topping requires: at most 10 toppings.", ...]
+      module Actions
+        module_function
+
+        # @param holder [Bluebook::Aggregate, Bluebook::Entity] the construct with a lifecycle
+        # @return [Array<String>] where it starts, then one sentence per move
+        def lifecycle(holder)
+          lifecycle = holder.respond_to?(:lifecycle) && holder.lifecycle
+          return [] unless lifecycle
+
+          start = "#{PlainEnglish.upper(PlainEnglish.a(PlainEnglish.noun(holder.hecks_name)))} " \
+                  "starts out #{PlainEnglish.state(lifecycle.default)}."
+          [start, *moves(lifecycle).map { |command, move| move_sentence(holder, command, move) }]
+        end
+
+        # Each command's moves, as `[command, { from: [...], to: state }]`, merged across the
+        # transitions a command declares from more than one state.
+        def moves(lifecycle)
+          merged = lifecycle.transitions.each_with_object({}) do |(command, transition), found|
+            key = [command.to_s, transition.target]
+            found[key] ||= { from: [], to: transition.target }
+            found[key][:from] |= Array(transition.from)
+          end
+          merged.map { |(command, _target), move| [command, move] }
+        end
+
+        # "Purchasing an order moves it from available to sold."
+        def move_sentence(holder, command, move)
+          doing = PlainEnglish.doing(command, holder.hecks_name)
+          noun = PlainEnglish.noun(holder.hecks_name)
+          object = doing.match?(/\b#{Regexp.escape(noun)}\b/) ? "it" : "the #{noun}"
+          "#{PlainEnglish.upper(doing)} #{move_phrase(move, object)}."
+        end
+
+        # "moves it from available to sold", "keeps it failed", or "moves it to closed".
+        #
+        # @param move [Hash] `{ from: [...], to: state }`, as `moves` answers it
+        # @param object [String] what is moved, such as "it" or "the order"
+        # @return [String] the verb phrase
+        def move_phrase(move, object)
+          to = PlainEnglish.state(move[:to])
+          return "keeps #{object} #{to}" if move[:from] == [move[:to]]
+          return "moves #{object} to #{to}" if move[:from].empty?
+
+          "moves #{object} from #{PlainEnglish.states(move[:from])} to #{to}"
+        end
+
+        # @param holder [Bluebook::Aggregate, Bluebook::Entity] the construct the commands are on
+        # @return [Array<String>] each command's role, its rules, and what it guarantees after
+        def rules(holder)
+          holder.commands.flat_map { |command| command_rules(holder, command) }
+        end
+
+        def command_rules(holder, command)
+          doing = PlainEnglish.doing(command.hecks_name, holder.hecks_name)
+          role = command.role && "#{PlainEnglish.upper(doing)} is done by the #{PlainEnglish.noun(command.role)}."
+          [role, *checks(holder, command).map { |rule| "#{PlainEnglish.upper(doing)} requires: #{rule}." },
+           *command.ensures.map { |rule| "After #{doing}: #{text(rule)}." }].compact
+        end
+
+        # What a command checks first: the state it starts from, then each `given` in the
+        # author's words. The state is left out when a move sentence already says it.
+        #
+        # @param said_by_move [Boolean] whether a move sentence states the starting state
+        # @return [Array<String>] the rules, without a closing period
+        def checks(holder, command, said_by_move: true)
+          [state_check(holder, command, said_by_move), *command.givens.map { |rule| text(rule) }].compact
+        end
+
+        # "the order is available", for a command declared `from:` a state.
+        def state_check(holder, command, said_by_move)
+          return nil unless command.from
+          return nil if said_by_move && moved_by?(holder, command)
+
+          "the #{PlainEnglish.noun(holder.hecks_name)} is #{PlainEnglish.states(Array(command.from))}"
+        end
+
+        def moved_by?(holder, command)
+          lifecycle = holder.respond_to?(:lifecycle) && holder.lifecycle
+          return false unless lifecycle
+
+          lifecycle.transitions.any? { |name, _transition| name.to_s == command.hecks_name }
+        end
+
+        # A rule's description as written, without a trailing period.
+        def text(rule) = rule.description.to_s.strip.delete_suffix(".")
+      end
+    end
+  end
+end

data/lib/hecks/projections/statements/relationships.rb

@@ -0,0 +1,86 @@
+require_relative "../plain_english"
+
+module Hecks
+  module Projections
+    module Statements
+      # What one thing holds or points at, said from its attribute's name, target and cardinality.
+      # A reference stored under its target's own name reads as belonging; one stored under a
+      # role ("source", "disputed_by") keeps the role, so two references to one target differ.
+      #
+      #   Relationships.sentence(transfer, source) # => "Each transfer has one source account."
+      module Relationships
+        PREPOSITIONS = %w[by to for from with of on in at].freeze
+
+        # The built-in value types, which a list names by its field rather than its element.
+        PRIMITIVES = %w[String Integer Float TrueClass FalseClass Boolean].freeze
+
+        module_function
+
+        # @param holder [Bluebook::Aggregate, Bluebook::Entity] the construct the attribute is on
+        # @param attribute [Bluebook::Attribute] one of its attributes
+        # @return [String, nil] the sentence, or nil for a plain field
+        def sentence(holder, attribute)
+          subject = "Each #{PlainEnglish.noun(holder.hecks_name)}"
+          return list_sentence(subject, attribute) if attribute.list?
+          return nil unless attribute.relationship
+
+          "#{subject} #{reference_phrase(attribute)}."
+        end
+
+        # "Each order holds a list of toppings." The element is named when the field is not
+        # simply its plural: "Each account holds its ledger, a list of ledger entries."
+        def list_sentence(subject, attribute)
+          field = PlainEnglish.noun(attribute.name)
+          element = element_noun(attribute)
+          return "#{subject} holds a list of #{field}." if element.nil? || field.end_with?(element)
+
+          "#{subject} holds its #{field}, a list of #{element}."
+        end
+
+        # The plural element noun, or nil for a list of plain values (text, numbers).
+        def element_noun(attribute)
+          type = attribute.type
+          name = type.respond_to?(:target_name) ? type.target_name : type.to_s
+          return nil if PRIMITIVES.include?(name) || name.include?("<")
+
+          PlainEnglish.plural(PlainEnglish.noun(name))
+        end
+
+        # The verb phrase after "Each <holder>".
+        def reference_phrase(attribute)
+          target_name = attribute.type.target_name
+          target = PlainEnglish.noun(target_name)
+          return own_name_phrase(attribute, target) if Naming.snake(target_name) == attribute.name.to_s
+
+          role = PlainEnglish.noun(attribute.name)
+          return prepositional_phrase(role, target, attribute.optional?) if PREPOSITIONS.include?(role.split.last)
+
+          role_phrase(role, target, attribute.optional?)
+        end
+
+        # "belongs to one customer", or "has one" for `has_one`; "can" when it is optional.
+        def own_name_phrase(attribute, target)
+          has = attribute.relationship == "has_one"
+          return "#{has ? "can have" : "can belong to"} one #{target}" if attribute.optional?
+
+          "#{has ? "has" : "belongs to"} one #{target}"
+        end
+
+        # "can be disputed by one customer", "reports to at most one employee".
+        def prepositional_phrase(role, target, optional)
+          if role.split.first.match?(/(ed|en|wn)\z/)
+            optional ? "can be #{role} one #{target}" : "is #{role} one #{target}"
+          else
+            optional ? "#{role} at most one #{target}" : "#{role} one #{target}"
+          end
+        end
+
+        # "has one source account"; a role that already ends in its target is not repeated.
+        def role_phrase(role, target, optional)
+          named = role.end_with?(target.split.last) ? role : "#{role} #{target}"
+          optional ? "can have one #{named}" : "has one #{named}"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/statements.rb

@@ -1,11 +1,15 @@
 require_relative "../projector"
+require_relative "statements/relationships"
+require_relative "statements/actions"
 
 module Hecks
   module Projections
-    # A domain's declared facts as flat plain-English sentences, one checkable statement per fact.
-    # Never invents one: relationships read from shape, invariants use the author's description.
+    # A domain's declared facts as flat plain-English sentences, one checkable statement per fact:
+    # what each thing holds and points at, what is always true of it, how it moves between
+    # states, and what each of its commands checks. Never invents one: relationships read from
+    # shape and names, and every rule uses the author's own description.
     #
-    #   Pizzas.project(Projections::Statements) # => ["A Pizza has many toppings.", ...]
+    #   Pizzas.project(Projections::Statements) # => ["Each order holds a list of toppings.", ...]
     module Statements
       extend Hecks::Projector::Target
 
@@ -18,8 +22,8 @@ module Hecks
       # @param bluebook [Bluebook::Chapter] the chapter being projected
       # @param options [Hash{Symbol => Object}] ignored; present to satisfy the
       #   `Projector::Target` calling convention
-      # @return [Array<String>] one sentence per attribute relationship and invariant,
-      #   in holder order
+      # @return [Array<String>] each holder's relationships, invariants, moves and command
+      #   rules, in holder order
       def call(bluebook:, options: {})
         holders(bluebook).flat_map { |holder| statements_for(holder) }
       end
@@ -27,31 +31,18 @@ module Hecks
       def holders(bluebook) = bluebook.aggregates.flat_map { |aggregate| [aggregate, *aggregate.entities] }
 
       def statements_for(holder)
-        attribute_statements(holder) + invariant_statements(holder)
+        attribute_statements(holder) + invariant_statements(holder) +
+          Actions.lifecycle(holder) + Actions.rules(holder)
       end
 
-      # `has_many` and `list_of` read the same in English; `attribute.name` is the author's noun.
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] the construct being read
+      # @return [Array<String>] one sentence per list or reference attribute
       def attribute_statements(holder)
         holder.attributes.filter_map { |attribute| attribute_statement(holder, attribute) }
       end
 
-      def attribute_statement(holder, attribute)
-        subject = "#{article(holder.hecks_name)} #{holder.hecks_name}"
-        return "#{subject} has many #{attribute.name}." if attribute.list?
-
-        target = attribute.relationship && attribute.type.target_name
-        target_phrase = target && "#{article(target).downcase} #{target}"
-        case attribute.relationship
-        when "has_one"      then "#{subject} has #{target_phrase}."
-        when "belongs_to"   then "#{subject} belongs to #{target_phrase}."
-        when "reference_to" then "#{subject} references #{target_phrase}."
-        end
-      end
-
-      # Vowel-letter heuristic is safe: construct names are plain words, never initialisms.
-      # @param word [String] a construct name to prefix
-      # @return [String] `"An"` if `word` starts with a vowel letter, `"A"` otherwise
-      def article(word) = word.to_s.match?(/\A[AEIOUaeiou]/) ? "An" : "A"
+      # @return [String, nil] the attribute's sentence, or nil for a plain field
+      def attribute_statement(holder, attribute) = Relationships.sentence(holder, attribute)
 
       # Invariants sit on the holder and on each nested value object; both are read.
       # @param holder [Bluebook::Aggregate, Bluebook::Entity] the construct whose

data/lib/hecks/projector/exporter/adapters.rb

@@ -0,0 +1,112 @@
+require "json"
+
+module Hecks
+  module Projector
+    module Exporter
+      # The declared `.adapter` constructs as plain Hashes, in the shape
+      # `hecks-parse adapter <file>...` prints as JSON, so the two parsers can be compared byte
+      # for byte.
+      module Adapters
+        # Every adapter declared in a registry, in declaration order.
+        #
+        # @param registry [Runtime::Registry] the registry the `.adapter` files were loaded into
+        # @return [Array<Hash{String => Object}>] each adapter as `adapter_hash` builds it
+        def adapters(registry)
+          registry.adapters.values.map { |adapter| adapter_hash(adapter) }
+        end
+
+        # Exports one adapter with string keys in the fixed order name, port, fields, secrets,
+        # defaults.
+        #
+        # @param adapter [Bluebook::Hecksagon::Adapter] the adapter to export
+        # @return [Hash{String => Object}] `"name"` (String), `"port"` (String, nil when never
+        #   declared), `"fields"`/`"secrets"` (`Array<String>`), `"defaults"` (field name to its
+        #   JSON-native default, in first-declaration order)
+        def adapter_hash(adapter)
+          {
+            "name"     => adapter.name,
+            "port"     => adapter.port,
+            "fields"   => (adapter.fields || []).map(&:to_s),
+            "secrets"  => (adapter.secrets || []).map(&:to_s),
+            "defaults" => adapter.declared_defaults.to_h { |field, value| [field.to_s, value] }
+          }
+        end
+
+        # Loads each `.adapter` file into its own fresh registry and exports what it declared,
+        # in file order then declaration order.
+        #
+        # @param paths [Array<String>] `.adapter` file paths
+        # @return [Array<Hash{String => Object}>] `adapters` of each loaded registry, concatenated
+        def adapters_in_files(paths)
+          paths.flat_map { |path| adapters(load_adapter_file(path)) }
+        end
+
+        # The adapters of the given files as the pretty JSON `hecks-parse adapter` prints for them,
+        # byte for byte: the bundled json's `JSON.pretty_generate`, whose spacing of an empty
+        # collection `hecks-parse` reproduces.
+        #
+        # @param paths [Array<String>] `.adapter` file paths
+        # @return [String] the JSON `hecks-parse adapter` prints for the same files
+        def adapters_json(paths)
+          JSON.pretty_generate(adapters_in_files(paths))
+        end
+
+        # Directories that hold copies or build output, never a source `.adapter`; the Rust
+        # builder skips the same names (and any dot-directory).
+        SKIPPED_DIRS = %w[target vendor node_modules tmp .git].freeze
+
+        # Every `.adapter` file under the given directories, for the IR's `adapters` key. The
+        # Rust builder scans the same directories the same way.
+        #
+        # @param directories [Array<String>] directories to scan recursively
+        # @return [Array<String>] absolute paths, unique and in byte order, none beneath a
+        #   skipped or hidden directory (relative to the directory scanned)
+        def adapter_files_under(directories)
+          directories.flat_map do |directory|
+            base = File.expand_path(directory)
+            Dir.glob(File.join(base, "**", "*.adapter")).reject do |path|
+              path.delete_prefix("#{base}/").split("/")[0...-1].any? { |part| SKIPPED_DIRS.include?(part) }
+            end
+          end.uniq.sort_by(&:b)
+        end
+
+        # The declarations of the adapters a domain binds, the IR's `adapters` key: one entry
+        # per distinct bound name that some `.adapter` file declares, in name byte order. Only
+        # declarations: never a world's setting values. A bound name nothing declares is
+        # omitted, for the host to refuse. Of two files declaring one name, the first path wins.
+        # A file is loaded only if it quotes a bound name, which cannot change the result.
+        #
+        # @param persistence [Hash{Symbol => Object}] `persistence`'s `:aggregates` with `:adapter`
+        # @param paths [Array<String>] candidate `.adapter` files, in precedence order
+        # @return [Array<Hash{String => Object}>] each as `adapter_hash` builds it
+        def persistence_adapters(persistence, paths)
+          wanted = bound_adapter_names(persistence)
+          declared = adapters_in_files(paths.select { |path| quotes_any?(File.read(path), wanted) })
+          declared.select { |adapter| wanted.include?(adapter["name"]) }.uniq { |a| a["name"] }
+                  .sort_by { |adapter| adapter["name"].b }
+        end
+
+        # @param persistence [Hash{Symbol => Object}] `persistence`'s result
+        # @return [Array<String>] the distinct adapter names its aggregates bind
+        def bound_adapter_names(persistence) = persistence.fetch(:aggregates).map { |row| row.fetch(:adapter) }.uniq
+
+        # @param text [String] a file's text
+        # @param names [Array<String>] adapter names
+        # @return [Boolean] whether the text quotes any of the names
+        def quotes_any?(text, names) = names.any? { |name| text.include?("\"#{name}\"") }
+
+        # Loads one `.adapter` file into a fresh registry. The file's own `require "hecks/..."`
+        # line loads the implementing class and needs `lib/` on the load path, as it is under
+        # bundler.
+        #
+        # @param path [String] an `.adapter` file path
+        # @return [Runtime::Registry] a registry holding only that file's adapters
+        def load_adapter_file(path)
+          registry = Runtime::Registry.new
+          Hecks.with_registry(registry) { Kernel.load(path) }
+          registry
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projector/exporter/translations.rb

@@ -38,33 +38,15 @@ module Hecks
           JSON.pretty_generate(translations(registry))
         end
 
-        # The digest-relevant shape `ApprovalDigest.edge_digest` hashes — declared rules only,
-        # never the compiled SQL, so a compiler-output change can't invalidate an approval.
-        #
-        # @param translation [Bluebook::Translation] the translation to digest
-        # @return [Hash{Symbol => Object}] `:domain` (String), `:from`/`:to` (the era
-        #   identifiers as declared), `:retired` (`Array<String>`), and `:aggregates`
-        #   (each `translation_aggregate`'s own Hash)
-        def translation_hash(translation)
-          {
-            domain:     translation.domain,
-            from:       translation.from,
-            to:         translation.to,
-            retired:    translation.retired,
-            aggregates: translation.aggregates.map { |aggregate| translation_aggregate(aggregate) }
-          }
-        end
-
-        # Digests one aggregate's own declared translation rules.
+        # One aggregate's declared translation rules as plain data.
         #
         # @param aggregate [Bluebook::TranslationAggregate] the aggregate's own
-        #   translation rules to digest
+        #   translation rules
         # @return [Hash{Symbol => Object}] `:name` (String), `:was` (String, nil),
-        #   `:renames` (`Hash{String => String}`), `:moves`/`:converts`/`:retypes`/
-        #   `:computes`/`:rekeys`/`:backfills` (each an `Array<Hash>`), `:drops`
-        #   (`Array<String>`)
+        #   `:renames` (`Hash{String => String}`), `:moves`/`:converts`/`:retypes`/`:backfills`
+        #   (each an `Array<Hash>`), `:drops` (`Array<String>`)
         def translation_aggregate(aggregate)
-          structural_rules(aggregate).merge(typed_rules(aggregate)).merge(computed_rules(aggregate))
+          structural_rules(aggregate).merge(typed_rules(aggregate)).merge(backfill_rules(aggregate))
         end
 
         # `translation_aggregate`'s fields, plus precompiled SQL from the same
@@ -78,7 +60,7 @@ module Hecks
         def compiled_translation_aggregate(aggregate)
           return translation_aggregate(aggregate) unless Ports::Persistence.plugin?(:era)
 
-          translation_aggregate(aggregate).merge(
+          translation_aggregate(aggregate).merge(derived_rules(aggregate)).merge(
             compiled_state_expression: Translation::RuleCompiler.compile_rules(aggregate),
             compiled_id_expression:    (if Translation::RuleCompiler.rekeyed?(aggregate)
                                           Translation::RuleCompiler.compile_id_expression(aggregate)
@@ -109,17 +91,18 @@ module Hecks
           }
         end
 
-        # The computes, rekeys and backfills of an aggregate.
-        #
-        # `rekeys`/`backfills` are digest-relevant too — a rekey with no compute
-        # would otherwise collide with any other, letting its SQL change silently
-        # invalidate nothing.
-        def computed_rules(aggregate)
-          {
-            computes:  aggregate.computes.map { |compute| { from: compute.from, to: compute.to, sql: compute.sql } },
-            rekeys:    aggregate.rekeys.map { |rekey| { sql: rekey.sql } },
-            backfills: aggregate.backfills.map { |backfill| { name: backfill.name.to_s, default: backfill.default } }
-          }
+        # The derives and the `rekey_to` of an aggregate, in the export of compiled rules only. An
+        # aggregate with none adds no key.
+        def derived_rules(aggregate)
+          return {} if aggregate.derives.empty?
+
+          rules = { derives: aggregate.derives.map { |derive| { to: derive.to, expression: derive.expression } } }
+          aggregate.rekeys.empty? ? rules : rules.merge(rekey_to: aggregate.rekeys.first.to)
+        end
+
+        # The backfills of an aggregate.
+        def backfill_rules(aggregate)
+          { backfills: aggregate.backfills.map { |backfill| { name: backfill.name.to_s, default: backfill.default } } }
         end
       end
     end

data/lib/hecks/projector/exporter/worlds.rb

@@ -0,0 +1,103 @@
+require "json"
+
+module Hecks
+  module Projector
+    module Exporter
+      # The declared `.world` constructs as plain Hashes, in the shape `hecks-parse world
+      # <file>...` prints as JSON, so the two parsers can be compared byte for byte. Only names are
+      # exported: a bind's setting values (connection strings, keys) never leave the file, and the
+      # default database is reported as a presence flag.
+      module Worlds
+        # Every world declared in a registry, one per domain, in first-declaration order.
+        #
+        # @param registry [Runtime::Registry] the registry the `.world` files were loaded into
+        # @return [Array<Hash{String => Object}>] each world as `world_hash` builds it
+        def worlds(registry)
+          registry.worlds.values.map { |world| world_hash(world) }
+        end
+
+        # Exports one world with string keys in the fixed order domain, realm, latest,
+        # default_adapter, default_database, bindings.
+        #
+        # @param world [Bluebook::World] the world to export
+        # @return [Hash{String => Object}] `"domain"` (String); `"realm"`, `"latest"` and
+        #   `"default_adapter"` (String, nil when unset or empty); `"default_database"` (true
+        #   only when a non-empty connection is declared, never the connection itself);
+        #   `"bindings"` (see `world_bindings`)
+        def world_hash(world)
+          {
+            "domain"           => world.domain,
+            "realm"            => present_string(world.realm),
+            "latest"           => present_string(world.latest),
+            "default_adapter"  => present_string(world.default_adapter),
+            "default_database" => !present_string(world.default_database).nil?,
+            "bindings"         => world_bindings(world)
+          }
+        end
+
+        # The adapter binds of a world, from the qualified `"verb:adapter"` settings entries only
+        # (the bare verb entry repeats the last of them), in the order they were declared.
+        #
+        # @param world [Bluebook::World] the world whose settings to read
+        # @return [Array<Hash{String => Object}>] each `"verb"` (as written), `"adapter"` and
+        #   `"settings"` (the setting names, never their values, in declaration order)
+        def world_bindings(world)
+          world.settings.filter_map do |key, value|
+            next unless key.include?(":")
+
+            adapter = value[:adapter].to_s
+            { "verb" => key.delete_suffix(":#{adapter.downcase}"), "adapter" => adapter,
+              "settings" => value.keys.reject { |name| name == :adapter }.map(&:to_s) }
+          end
+        end
+
+        # Loads every given `.world` file, in order, into one fresh registry, so worlds of one
+        # domain merge as they do at boot, and exports what it holds.
+        #
+        # @param paths [Array<String>] `.world` file paths
+        # @return [Array<Hash{String => Object}>] `worlds` of that registry
+        def worlds_in_files(paths)
+          registry = Runtime::Registry.new
+          Hecks.with_registry(registry) { paths.each { |path| Kernel.load(path) } }
+          worlds(registry)
+        end
+
+        # The worlds of the given files as the pretty JSON `hecks-parse world` prints for them,
+        # byte for byte: the bundled json's `JSON.pretty_generate`.
+        #
+        # @param paths [Array<String>] `.world` file paths
+        # @return [String] the JSON `hecks-parse world` prints for the same files
+        def worlds_json(paths)
+          JSON.pretty_generate(worlds_in_files(paths))
+        end
+
+        # The IR's `world` key: what a domain's world says about persistence, names only. A missing
+        # file, or a file with no world for the domain, gives the empty default.
+        #
+        # @param path [String] the `.world` file the domain sits beside (it need not exist)
+        # @param domain [String] the target domain's name
+        # @return [Hash{String => Object}] `"default_adapter"` (String or nil), `"default_database"`
+        #   (Boolean) and `"persistence"` (each `persisted_by` bind as `"adapter"` and the
+        #   `"settings"` names)
+        def persistence_world(path, domain)
+          world = (File.file?(path) ? worlds_in_files([path]) : []).find { |entry| entry["domain"] == domain }
+          return { "default_adapter" => nil, "default_database" => false, "persistence" => [] } unless world
+
+          { "default_adapter" => world["default_adapter"], "default_database" => world["default_database"],
+            "persistence" => persisted_by_binds(world["bindings"]) }
+        end
+
+        # @param bindings [Array<Hash{String => Object}>] a world's `"bindings"`
+        # @return [Array<Hash{String => Object}>] the `persisted_by` ones, adapter and setting names
+        def persisted_by_binds(bindings)
+          bindings.select { |bind| bind["verb"] == "persisted_by" }
+                  .map { |bind| { "adapter" => bind["adapter"], "settings" => bind["settings"] } }
+        end
+
+        # @param value [String, nil] a scalar a world may leave unset
+        # @return [String, nil] the value, or nil when it is nil or empty
+        def present_string(value) = value.nil? || value.empty? ? nil : value
+      end
+    end
+  end
+end

data/lib/hecks/projector/exporter.rb

@@ -1,7 +1,9 @@
 require "json"
 require_relative "../ports/persistence"
+require_relative "exporter/adapters"
 require_relative "exporter/bindings"
 require_relative "exporter/translations"
+require_relative "exporter/worlds"
 
 module Hecks
   module Projector
@@ -9,7 +11,7 @@ module Hecks
     # binding facts, and translation edges (declared and compiled).
     #
     # The capability bindings (`authorization`, `membership`, ...) are `Exporter::Bindings` and
-    # the translation edges (`translations`, `translation_hash`, ...) are `Exporter::Translations`;
+    # the translation edges (`translations`, `translations_json`, ...) are `Exporter::Translations`;
     # both are reachable as methods of `Exporter` itself.
     module Exporter
       module_function
@@ -72,8 +74,10 @@ module Hecks
         { aggregates: aggregates }
       end
 
+      extend Adapters
       extend Bindings
       extend Translations
+      extend Worlds
     end
   end
 end