hecks 5.0.0 → 7.0.0

data/lib/hecks/ports/persistence/append_only.rb

@@ -1,5 +1,6 @@
 require_relative "../../runtime/registry"
 require_relative "execution"
+require_relative "set_transforming"
 
 module Hecks
   module Ports
@@ -11,7 +12,11 @@ module Hecks
       # (set by `append` on a live write, or by `entries`/`entries_since` on
       # a replayed one); nil for an adapter that assigns none. It rides
       # along so `project` can advance a checkpoint without a second lookup.
-      Entry = Struct.new(:operation, :id, :state, :mirrors, :sequence, keyword_init: true) do
+      #
+      # `mints_era` is the one-write allowance a command declared with `mints_era true` holds:
+      # only this entry, the command's own record, may be journaled through a boot whose shape no
+      # era holds yet. Nothing about it is persisted.
+      Entry = Struct.new(:operation, :id, :state, :mirrors, :sequence, :mints_era, keyword_init: true) do
         # Tells a projecting adapter that this entry writes a record.
         #
         # @return [Boolean] true when `operation` is the String `"save"`
@@ -21,11 +26,16 @@ module Hecks
         #
         # @return [Boolean] true when `operation` is the String `"delete"`
         def delete? = operation == "delete"
+
+        # @return [Boolean] true when the command that wrote this entry declared `mints_era true`
+        def mints_era? = mints_era == true
       end
 
       # Makes append-before-projection a port invariant: adapters keep their own durable
       # format, but must accept the same entry stream and materialize state from it.
       class AppendOnly
+        include SetTransforming
+
         attr_reader :adapter
 
         # Names the aggregate this repository stores, as the wrapped adapter holds it.
@@ -46,6 +56,14 @@ module Hecks
                 "#{adapter.class} does not implement append-only persistence: #{missing.join(", ")}"
         end
 
+        # Whether the adapter's binding names this command as one whose own record an unminted
+        # boot may write (`mints_era` in the world); an adapter with no such binding says no.
+        #
+        # @param agg [String] the aggregate the command belongs to
+        # @param name [String] the command
+        # @return [Boolean]
+        def mints_era_declared?(agg, name) = adapter.respond_to?(:mints_era_declared?) && adapter.mints_era_declared?(agg, name)
+
         # Reads one record's current projected state from the adapter.
         #
         # @param id [String, Object] the record's identity; adapters compare it as `id.to_s`
@@ -180,15 +198,16 @@ module Hecks
         # Returns an Outcome, not a bare Instance, so callers can check `:saved` vs `:stale`;
         # `expected_version:` only triggers CAS on an adapter declaring `:optimistic_concurrency`.
         #
-        # @param instance [Runtime::Instance] the record to persist; its `state` is shallow
-        #   copied into the entry
+        # @param instance [Runtime::Instance] the record to persist; its `state` is shallow copied
         # @param expected_version [Integer, nil] the version the instance was read at, or nil
         #   for an unconditional write
+        # @param mints_era [Boolean] true when the writing command declares `mints_era true`
         # @return [Persistence::Outcome] status `:saved` or `:stale`; `instance` is the
         #   adapter's projected result on `:saved`, else the instance passed in
         # @raise [Runtime::WiringError] when the adapter's `append` or `project` refuses
-        def save(instance, expected_version: nil)
-          entry = Entry.new(operation: "save", id: instance.id.to_s, state: instance.state.dup)
+        def save(instance, expected_version: nil, mints_era: false)
+          entry = Entry.new(operation: "save", id: instance.id.to_s, state: instance.state.dup,
+                            mints_era: mints_era)
           append(entry)
           if expected_version && capabilities.include?(:optimistic_concurrency)
             saved = @adapter.project(entry, expected_version: expected_version)
@@ -205,19 +224,21 @@ module Hecks
         #
         # @param instance [Runtime::Instance] the record to persist
         # @param insert_only [Boolean] true to refuse replacing a record that already exists
+        # @param mints_era [Boolean] true when the writing command declares `mints_era true`
         # @return [Persistence::Outcome] status `:inserted`, `:replaced`, or `:conflicted` when
         #   `insert_only` met an existing record and nothing was written; `instance` is always
         #   the instance passed in
         # @raise [Runtime::WiringError] if the adapter does not both advertise `:atomic_put`
         #   and implement it
         # @raise [ArgumentError] if the adapter answers a status outside `Outcome::STATUSES`
-        def atomic_put(instance, insert_only: false)
+        def atomic_put(instance, insert_only: false, mints_era: false)
           unless capabilities.include?(:atomic_put) && @adapter.respond_to?(:atomic_put)
             raise Runtime::WiringError,
                   "#{@adapter.class} advertises no atomic_put persistence capability"
           end
 
-          entry = Entry.new(operation: "save", id: instance.id.to_s, state: instance.state.dup)
+          entry = Entry.new(operation: "save", id: instance.id.to_s, state: instance.state.dup,
+                            mints_era: mints_era)
           status = @adapter.atomic_put(entry, insert_only: insert_only)
           Outcome.new(status: status, instance: instance)
         end
@@ -228,7 +249,7 @@ module Hecks
         # @return [Boolean] true when a record was found and deleted, false when there was
         #   none and nothing was journaled
         # @raise [Runtime::WiringError] when the adapter's `append` or `project` refuses
-        def delete(id) # rubocop:disable Naming/PredicateMethod -- the repository port's verb, answering whether a record existed
+        def delete(id)
           return false unless find(id)
 
           entry = Entry.new(operation: "delete", id: id.to_s, state: nil)
@@ -323,13 +344,27 @@ module Hecks
         # @return [Array<Runtime::Outbox::Row>] copies of the stored rows; `[]` when none match
         def outbox_rows(status: nil) = @adapter.outbox_rows(status: status)
 
+        # Whether a saga dispatch with this key has been applied. Call only when `capabilities`
+        # lists `:dispatch_claims`.
+        #
+        # @param key [String] the dispatch key a saga leg stamped on the command
+        # @return [Boolean] true once `dispatch_claim` has accepted the key
+        def dispatch_applied?(key) = @adapter.dispatch_applied?(key)
+
+        # Records that a saga dispatch is being applied, inside the save's transaction. Call only
+        # when `capabilities` lists `:dispatch_claims`.
+        #
+        # @param key [String] the dispatch key a saga leg stamped on the command
+        # @return [Boolean] true when the key was new and is now held; false when already held
+        def dispatch_claim(key) = @adapter.dispatch_claim(key)
+
         # Answers a read model from the adapter's own projected tables, when it can.
         #
         # @param domain [String, Symbol] name of the domain declaring the read model
         # @param model [Bluebook::ReadModel] the read model to answer
         # @param args [Hash{Symbol => Object}] the read model's arguments, including its
         #   reference argument
-        # @param bluebook [Bluebook::Chapter, nil] the domain's bluebook, which the SQLite
+        # @param bluebook [Bluebook::Declaration, nil] the domain's bluebook, which the SQLite
         #   projection needs to find the included aggregates
         # @return [Array<Hash>, nil] a one-element Array holding the report Hash keyed by head
         #   name; nil when the adapter has no `query_read_model`

data/lib/hecks/ports/persistence/binding_policy.rb

@@ -9,27 +9,69 @@ module Hecks
       module BindingPolicy
         module_function
 
-        # Picks the one bind that names an aggregate's authoritative store. A world's
-        # `default_adapter` only fills a hecksagon's gap; an explicit bind always wins.
+        # Picks the one bind that names an aggregate's authoritative store: its own bind, its
+        # bluebook's root default, an attaching domain's root default, a world's `default_adapter`,
+        # then Memory. A hecksagon that binds some aggregates and leaves this one out is refused
+        # as a forgotten decision; one that never mentions persistence has made none.
         #
         # @param registry [Runtime::Registry] the registry holding the domain's hecksagon
         # @param domain [String, Symbol] name of the domain the aggregate belongs to
         # @param aggregate [Bluebook::Aggregate] the aggregate whose binding is wanted
-        # @return [Bluebook::Bind] the authoritative `persisted_by` bind, or the default
-        #   `Memory` bind when the domain declares no hecksagon
-        # @raise [Runtime::WiringError] if the hecksagon has no `persisted_by` bind for the
-        #   aggregate, more or fewer than one bind without a role, or any bind with a role
+        # @return [Bluebook::Bind] the authoritative `persisted_by` bind
+        # @raise [Runtime::WiringError] if some aggregates are bound and this one is not, the
+        #   roleless
+        #   binds are not exactly one, a bind has a role, or attaching domains disagree
         def resolve(registry, domain, aggregate)
           hecksagon = registry.hecksagon(domain)
           declared  = registry.default_adapter_for(domain)
           return default_binding(aggregate, declared || DEFAULT_ADAPTER) unless hecksagon
 
-          bindings = declared_bindings(hecksagon, aggregate, declared)
+          bindings = declared_bindings(registry, domain, hecksagon, aggregate, declared)
+          return default_binding(aggregate) if bindings.empty? && !wired?(hecksagon)
           raise missing_binding(domain, aggregate) if bindings.empty?
 
           authoritative_among(bindings, domain, aggregate)
         end
 
+        # Whether a hecksagon has made a persistence decision: it binds some aggregate, or the
+        # domain, to an adapter other than the default. A bind to Memory decides nothing the
+        # default had not, so it does not count.
+        #
+        # @param hecksagon [Bluebook::Hexagon] the domain's hecksagon
+        # @return [Boolean]
+        def wired?(hecksagon)
+          hecksagon.binds.any? { |bind| bind.verb.to_s == VERB && bind.adapter.to_s != DEFAULT_ADAPTER }
+        end
+
+        # Whether a domain's hecksagon leaves persistence entirely unwired: no bind of its own, no
+        # default handed down by an attaching domain, and no world default.
+        #
+        # @param registry [Runtime::Registry] the registry holding the domain's hecksagon
+        # @param domain [String, Symbol] name of the domain
+        # @return [Boolean] false when the domain declares no hecksagon at all
+        def unwired?(registry, domain)
+          hecksagon = registry.hecksagon(domain)
+          return false unless hecksagon
+
+          !wired?(hecksagon) && registry.default_adapter_for(domain).nil? && inherited_adapter(registry, domain).nil?
+        end
+
+        # The adapter the root default of an attaching domain hands to a bluebook it attaches, so
+        # one
+        # `persisted_by` at a domain's root reaches the bluebooks it brings in.
+        #
+        # @param registry [Runtime::Registry] the registry holding every hecksagon
+        # @param domain [String, Symbol] name of the attached bluebook
+        # @return [String, nil] the adapter, nil when no attaching domain declares a default
+        # @raise [Runtime::WiringError] if two attaching domains declare different defaults
+        def inherited_adapter(registry, domain)
+          attachers = registry.hecksagons.values.select { |hecksagon| hecksagon.attaches?(domain) }
+          adapters  = attachers.flat_map { |hecksagon| hecksagon.default_binds(VERB) }.map(&:adapter).uniq
+          raise conflicting_defaults(domain, adapters) if adapters.size > 1
+
+          adapters.first
+        end
+
         # Picks the single roleless bind, refusing any other count and any bind with a role.
         #
         # @param bindings [Array<Bluebook::Bind>] the aggregate's binds; not empty
@@ -38,7 +80,9 @@ module Hecks
         # @return [Bluebook::Bind] the authoritative bind
         # @raise [Runtime::WiringError] if the roleless count is not one, or a role is present
         def authoritative_among(bindings, domain, aggregate)
-          authoritative = bindings.select { |bind| bind.role.nil? || bind.role.empty? }
+          # The same adapter declared again, by a hecksagon that another domain also attaches, is one
+          # binding, not an ambiguous second one.
+          authoritative = bindings.select { |bind| bind.role.nil? || bind.role.empty? }.uniq(&:adapter)
           raise ambiguous_binding(domain, aggregate, authoritative) unless authoritative.size == 1
 
           roled = bindings - authoritative
@@ -47,16 +91,33 @@ module Hecks
           authoritative.first
         end
 
-        # Lists the hecksagon's `persisted_by` binds for an aggregate, or the world's default
-        # adapter bind when the hecksagon declares none.
+        # Lists the hecksagon's `persisted_by` binds for an aggregate, or else the bind an attaching
+        # domain's root default or the world's default adapter gives it.
         #
+        # @param registry [Runtime::Registry] the registry holding every hecksagon
+        # @param domain [String, Symbol] name of the aggregate's domain
         # @param hecksagon [Bluebook::Hexagon] the domain's hecksagon
         # @param aggregate [Bluebook::Aggregate] the aggregate whose binds are wanted
         # @param declared [String, nil] the world's default adapter, if any
         # @return [Array<Bluebook::Bind>] the binds; empty when none and no default exists
-        def declared_bindings(hecksagon, aggregate, declared)
+        def declared_bindings(registry, domain, hecksagon, aggregate, declared)
           bindings = hecksagon.binds_for(aggregate.hecks_name, VERB)
-          bindings.empty? && declared ? [default_binding(aggregate, declared)] : bindings
+          return bindings unless bindings.empty?
+
+          fallback = inherited_adapter(registry, domain) || declared
+          fallback ? [default_binding(aggregate, fallback)] : []
+        end
+
+        # Builds, without raising, the error for attaching domains that declare different defaults.
+        #
+        # @param domain [String, Symbol] name of the attached bluebook
+        # @param adapters [Array<String>] the differing defaults
+        # @return [Runtime::WiringError] an error whose message names the adapters
+        def conflicting_defaults(domain, adapters)
+          Runtime::WiringError.new(
+            "#{domain} is attached by domains that bind #{VERB} by default to different adapters " \
+            "(#{adapters.join(", ")}). Bind #{domain} itself, or make the attaching domains agree."
+          )
         end
 
         # Builds the bind an aggregate gets when its domain declares no hecksagon.

data/lib/hecks/ports/persistence/codec_boundary.rb

@@ -59,11 +59,12 @@ module Hecks
         def check_entries!(adapter, entries)
           return entries unless entries.is_a?(Array)
 
+          aggregate = adapter.aggregate
           entries.each do |entry|
-            next unless entry.is_a?(Entry) && !StateCodec.decoded?(adapter.aggregate, entry.state)
+            next unless entry.is_a?(Entry) && !StateCodec.decoded?(aggregate, entry.state)
 
             raise Runtime::WiringError,
-                  "#{adapter.class} answered a #{adapter.aggregate.name} journal entry #{entry.id.inspect} with " \
+                  "#{adapter.class} answered a #{aggregate.name} journal entry #{entry.id.inspect} with " \
                   "undecoded state — decode it through Hecks::Ports::Persistence::StateCodec.decode"
           end
           entries
@@ -82,7 +83,7 @@ module Hecks
         module Guarded; end
 
         # A per-adapter-class cache, filled lazily under `WRAPPERS_LOCK`; deliberately mutable.
-        WRAPPERS = {} # rubocop:disable Style/MutableConstant
+        WRAPPERS = {}
         WRAPPERS_LOCK = Mutex.new
 
         # Builds, or fetches from the cache, the module that guards one adapter class.

data/lib/hecks/ports/persistence/mint_door.rb

@@ -0,0 +1,74 @@
+require_relative "../../runtime/errors"
+
+module Hecks
+  module Ports
+    module Persistence
+      # The commands whose own record an unminted boot may write, as a persistence binding names
+      # them: `persisted_by("PostgresEra") { mints_era "Maintenance.MintEra" }` in a world. This is
+      # where the allowance lives; the `mints_era true` a command can still carry is read as a
+      # fallback, and the two must agree.
+      #
+      # A name is `Aggregate.Command`. The world may give one name or a list.
+      module MintDoor
+        module_function
+
+        # @param settings [Hash{Symbol, String => Object}] a persistence binding's settings
+        # @return [Array<String>] the `Aggregate.Command` names the binding declares, else `[]`
+        def names(settings)
+          Array(settings.transform_keys(&:to_sym)[:mints_era]).map(&:to_s)
+        end
+
+        # @param settings [Hash] a persistence binding's settings
+        # @param aggregate_name [String] the aggregate the command belongs to
+        # @param command_name [String] the command
+        # @return [Boolean] true when the binding names `aggregate_name.command_name`
+        def declared?(settings, aggregate_name, command_name)
+          names(settings).include?("#{aggregate_name}.#{command_name}")
+        end
+
+        # Checks the binding against the bluebook it serves, before anything is written.
+        #
+        # A binding that names no command leaves the bluebook word alone. One that does must name
+        # only commands the bluebook declares, and every command the bluebook flags with
+        # `mints_era true` must be among them, so the two never disagree about who may write.
+        #
+        # @param bluebook [Bluebook::Declaration] the bluebook the binding serves
+        # @param settings [Hash] the binding's settings
+        # @return [void]
+        # @raise [Runtime::WiringError] naming the command when the two disagree
+        def check!(bluebook, settings)
+          declared = names(settings)
+          return if declared.empty?
+
+          known = commands_of(bluebook)
+          unknown = declared - known.keys
+          raise_unknown!(bluebook, unknown, known) unless unknown.empty?
+
+          unnamed = known.select { |name, flagged| flagged && !declared.include?(name) }.keys
+          raise_unnamed!(bluebook, unnamed, declared) unless unnamed.empty?
+        end
+
+        # @return [Hash{String => Boolean}] `Aggregate.Command` => whether it says `mints_era true`
+        def commands_of(bluebook)
+          bluebook.aggregates.flat_map do |aggregate|
+            aggregate.commands.map { |command| ["#{aggregate.hecks_name}.#{command.hecks_name}", command.mints_era?] }
+          end.to_h
+        end
+
+        def raise_unknown!(bluebook, unknown, known)
+          raise Runtime::WiringError,
+                "the world's mints_era names #{unknown.join(", ")}, but #{bluebook.name} declares no such command " \
+                "(its commands: #{known.keys.join(", ")}). A name that matches nothing would let no write through " \
+                "an unminted boot, so the boot refuses."
+        end
+
+        def raise_unnamed!(bluebook, unnamed, declared)
+          raise Runtime::WiringError,
+                "#{unnamed.join(", ")} declares `mints_era true` in #{bluebook.name}, but the world's mints_era " \
+                "(#{declared.join(", ")}) does not name it. Name it in the world, or remove the word from the " \
+                "command: the two must agree."
+        end
+      end
+    end
+  end
+end

data/lib/hecks/ports/persistence/plugins/era/era_check.rb

@@ -3,9 +3,9 @@ require_relative "../../../../ports/persistence/binding_policy"
 require_relative "lineage"
 require_relative "../../../../naming"
 require_relative "../../../../framework"
-require_relative "../../../../chapters"
+require_relative "../../../../framework_bluebooks"
+require_relative "../../../../module_folders"
 require_relative "../../../../runtime/registry"
-require_relative "expected_era"
 
 module Hecks
   module Runtime
@@ -68,18 +68,18 @@ module Hecks
 
       # Reads the source text one bluebook was declared in, wherever that source lives.
       #
-      # Matched by declared name, not position: a domain directory using
-      # `attaches` may hold more than one file, and a framework
-      # member or vendored bluebook is excluded from the single-file
-      # fallback so its own real source is read, not a sibling's.
+      # Matched by declared name, not position, over the files the loader reads in its order
+      # (ModuleFolders.all): a held era freezes this text, so a domain split into module folders
+      # is held whole. A framework member or vendored bluebook is left out of the single-file
+      # fallback so its own source is read, not a sibling's.
       #
-      # @param bluebook [Bluebook::Chapter] the bluebook whose source is wanted
+      # @param bluebook [Bluebook::Declaration] the bluebook whose source is wanted
       # @param directory [String] path of the domain's own bluebook directory
       # @param registry [Runtime::Registry, nil] nil skips the vendored-bluebook lookup
       # @return [String, nil] UTF-8 text of every matching file joined with `"\n"`, or nil
       def source_text_for(bluebook, directory, registry: nil)
         domain_files = Dir[File.join(directory, "*.bluebook")]
-        own = domain_files.select { |path| declares_bluebook?(path, bluebook.name) }
+        own = ModuleFolders.all(directory).select { |path| declares_bluebook?(path, bluebook.name) }
         own = fallback_source_files(bluebook, directory, domain_files, registry) if own.empty?
         return if own.empty?
 
@@ -101,10 +101,10 @@ module Hecks
 
       # Picks the files to read for a bluebook no file in the domain directory declares.
       #
-      # Tries, in order: a chapter the gem carries (the QA ledger's QualityControl), the domain's
+      # Tries, in order: a bluebook the gem carries (the QA ledger's QualityControl), the domain's
       # own single remaining file, a framework member, then a vendored embryonaut bluebook.
       #
-      # @param bluebook [Bluebook::Chapter] the bluebook whose source is wanted
+      # @param bluebook [Bluebook::Declaration] the bluebook whose source is wanted
       # @param directory [String] path of the domain's own bluebook directory
       # @param domain_files [Array<String>] paths of every `.bluebook` file in `directory`
       # @param registry [Runtime::Registry, nil] the registry asked for a vendored name; nil
@@ -116,7 +116,7 @@ module Hecks
         return [framework_path] if framework_path
         return vendored_source_for(directory, vendored_name) if vendored_name
 
-        attached = Chapters.index.fetch(bluebook.name, [])
+        attached = FrameworkBluebooks.index.fetch(bluebook.name, [])
         return attached if attached.any?
 
         domain_files.size == 1 ? domain_files : []
@@ -125,7 +125,7 @@ module Hecks
       # Recovers the vendored package name behind a bluebook, if some hecksagon vendored it.
       #
       # Matched first by Pascal-casing (the package name Pascal-cases to the bluebook's declared
-      # name), then by the package's own files: a package whose chapter is named otherwise (the
+      # name), then by the package's own files: a package whose bluebook is named otherwise (the
       # package `gallery` declaring `Galleries`) is the one whose files declare that name.
       #
       # @param registry [Runtime::Registry] the registry whose hecksagons are searched
@@ -135,7 +135,8 @@ module Hecks
       # @return [String, nil] the package name as written in `attaches ... from: :vendor`; nil
       #   when no vendored package matches `bluebook_name` by name or by declaration
       def vendored_bluebook_name_for(registry, bluebook_name, directory)
-        names = registry.hecksagons.each_value.flat_map(&:vendored_packages).uniq
+        hecksagons = registry.hecksagons.each_value
+        names = hecksagons.flat_map(&:vendored_packages).uniq
         names.find { |name| Naming.pascal(name) == bluebook_name } ||
           names.find { |name| declared_by_package?(directory, name, bluebook_name) }
       end
@@ -172,7 +173,7 @@ module Hecks
       # The first aggregate is the anchor: its binding alone decides the adapter asked.
       #
       # @param registry [Runtime::Registry] the registry being booted
-      # @param bluebook [Bluebook::Chapter] the bluebook to check
+      # @param bluebook [Bluebook::Declaration] the bluebook to check
       # @param current_text [String, nil] the bluebook's source; nil means none was found
       # @param directory [String, nil] the domain's bluebook directory, named in the refusal
       # @return [void]
@@ -197,7 +198,7 @@ module Hecks
 
       # Refuses the boot of a lineage-bound bluebook whose source file was not found.
       #
-      # @param bluebook [Bluebook::Chapter] the bluebook being checked
+      # @param bluebook [Bluebook::Declaration] the bluebook being checked
       # @param directory [String, nil] the domain's bluebook directory, named in the message
       # @return [void]
       # @raise [Runtime::WiringError] always

data/lib/hecks/ports/persistence/plugins/era/era_guard/shape_diff.rb

@@ -36,11 +36,10 @@ module Hecks
         def unsafe_additions(aggregate, held_aggregate, lineage)
           held_names = held_aggregate.attributes.map(&:name)
 
-          aggregate.attributes
-                   .reject { |attribute| held_names.include?(attribute.name) }
-                   .select { |attribute| possibly_absent?(aggregate, attribute) }
-                   .reject { |attribute| lineage&.fills?(attribute.name.to_s) }
-                   .map(&:name)
+          added = aggregate.attributes.reject { |attribute| held_names.include?(attribute.name) }
+          added.select { |attribute| possibly_absent?(aggregate, attribute) }
+               .reject { |attribute| lineage&.fills?(attribute.name.to_s) }
+               .map(&:name)
         end
 
         # True when a new attribute could be genuinely absent from an existing record (ADR 0025).
@@ -69,10 +68,14 @@ module Hecks
           paths.reject { |path| lineage.explains?(path) }
         end
 
-        # Compares one path's held and current types, recursing into shared members.
+        # Compares one path's held and current types, recursing into shared members. A type is
+        # compared by its name: a stored shape holds every type as its string
+        # (`"Reference<Target>"`), a declared bluebook may hold an object that prints the same.
         # A `list_of` entity is diffed only for member drift; no per-element translation exists, so
         # only a top-level `drop` of the whole list satisfies it.
         def diff_type(path, held_type, current_type, sides, seen = [])
+          held_type = held_type.to_s
+          current_type = current_type.to_s
           return [path] if retype_drift?(held_type, current_type, sides.lineage)
           return [] if seen.include?(current_type)
 

data/lib/hecks/ports/persistence/plugins/era/era_guard.rb

@@ -20,8 +20,8 @@ module Hecks
       # `retired` translation can explain it.
       #
       # @param registry [Runtime::Registry] the registry searched for a `was:`/`retired` entry
-      # @param bluebook [Bluebook::Chapter] the bluebook booting now
-      # @param held_bluebook [Bluebook::Chapter] the bluebook parsed from the held era's text
+      # @param bluebook [Bluebook::Declaration] the bluebook booting now
+      # @param held_bluebook [Bluebook::Declaration] the bluebook parsed from the held era's text
       # @return [void]
       # @raise [Runtime::WiringError] if a held aggregate matches no current aggregate, no
       #   `was:` declares it, and no translation retires it
@@ -39,7 +39,7 @@ module Hecks
       # or retired by a translation.
       #
       # @param registry [Runtime::Registry] the registry whose translations are searched
-      # @param bluebook [Bluebook::Chapter] the bluebook booting now
+      # @param bluebook [Bluebook::Declaration] the bluebook booting now
       # @param held_aggregate [Bluebook::Aggregate] the aggregate from the held era
       # @return [Boolean] true when a current aggregate or a translation explains it
       def explained?(registry, bluebook, held_aggregate)
@@ -54,7 +54,7 @@ module Hecks
       # Says whether a translation declares a current aggregate was the held one.
       #
       # @param registry [Runtime::Registry] the registry whose translations are searched
-      # @param bluebook [Bluebook::Chapter] the bluebook booting now
+      # @param bluebook [Bluebook::Declaration] the bluebook booting now
       # @param aggregate [Bluebook::Aggregate] the current aggregate
       # @param held_aggregate [Bluebook::Aggregate] the aggregate from the held era
       # @return [Boolean] true when some translation's `was:` names the held aggregate
@@ -71,7 +71,7 @@ module Hecks
       # calls it (today, `PostgresEra::LineageManager::CoverageCheck`'s
       # own mint-time coverage check).
       #
-      # @param bluebook [Bluebook::Chapter] the bluebook booting now, named in the message
+      # @param bluebook [Bluebook::Declaration] the bluebook booting now, named in the message
       # @param aggregate [Bluebook::Aggregate] the aggregate whose shape changed
       # @param uncovered [Array<String>] the unexplained paths, as `uncovered_attributes`
       #   returns them; must not be empty, since the first one seeds the suggested rule
@@ -91,7 +91,7 @@ module Hecks
       # wording shape, different cause: nothing vanished or changed type,
       # something new arrived that an existing record has no way to hold.
       #
-      # @param bluebook [Bluebook::Chapter] the bluebook booting now, named in the message
+      # @param bluebook [Bluebook::Declaration] the bluebook booting now, named in the message
       # @param aggregate [Bluebook::Aggregate] the aggregate that gained the attributes
       # @param unsafe [Array<Symbol>] the attribute names, as `unsafe_additions` returns them;
       #   must not be empty, since the first one seeds the suggested `backfill`
@@ -134,7 +134,7 @@ module Hecks
       #
       # @param source [String] the held bluebook text to evaluate
       # @param path [String] the file path reported as the text's origin
-      # @return [Bluebook::Chapter, nil] the first bluebook declared; nil when it declares none
+      # @return [Bluebook::Declaration, nil] the first bluebook declared; nil when it declares none
       # @raise [Bluebook::DSL::Malformed] if neither grammar accepts the text
       # @raise [SyntaxError] if the text is not valid Ruby
       def shadow_parse(source, path)
@@ -149,7 +149,7 @@ module Hecks
       # @param path [String] the file path reported to `Kernel.eval` as the text's origin
       # @param shadow [Boolean] true evaluates inside `MetaValidator.while_shadow_parsing`
       #   (the shadow grammar); false evaluates under the live grammar
-      # @return [Bluebook::Chapter, nil] the first bluebook the text registered in the scratch
+      # @return [Bluebook::Declaration, nil] the first bluebook the text registered in the scratch
       #   registry; nil when it declares none
       # @raise [Bluebook::DSL::Malformed] if the chosen grammar refuses the text
       # @raise [SyntaxError] if the text is not valid Ruby
@@ -158,7 +158,7 @@ module Hecks
         loading = Ports::Loading.bootstrap
         run = -> { evaluate_into(scratch, loading, source, path) }
         shadow ? Hecks::Bluebook::MetaValidator.while_shadow_parsing(&run) : run.call
-        scratch.bluebooks.values.first
+        scratch.first_bluebook
       end
 
       # Loads the library and evaluates the text with the scratch registry current.
@@ -171,8 +171,8 @@ module Hecks
       def evaluate_into(scratch, loading, source, path)
         Hecks.with_registry(scratch) do
           loading.load_library
-          # Held text of a chapter spread over files is several blocks in one string, each
-          # opening the same chapter: judge once after all of them, as a directory load does.
+          # Held text of a bluebook spread over files is several blocks in one string, each
+          # opening the same bluebook: judge once after all of them, as a directory load does.
           Hecks::Bluebook::MetaValidator.defer { Kernel.eval(source, TOPLEVEL_BINDING, path, 1) }
           Hecks::Bluebook::MetaValidator.judge_deferred!(scratch)
         end

data/lib/hecks/ports/persistence/plugins/era/era_status.rb

@@ -0,0 +1,48 @@
+require_relative "era_check"
+require_relative "storage_shape"
+
+module Hecks
+  module Runtime
+    # What a boot would resolve for each bluebook a registry loaded, asked of the same adapter the
+    # boot's era gate asks (`EraCheck`), against the database each bluebook's own world declares.
+    # Nothing is minted, provisioned or recorded: an era-holding adapter answers over a connection
+    # that can only read. A bluebook bound to an adapter that holds no eras answers `no_eras`.
+    module EraStatus
+      module_function
+
+      # @param registry [Runtime::Registry] the loaded registry, as a boot loads it
+      # @param directory [String] the domain's bluebook directory
+      # @return [Hash{String => Hash}] each bluebook's status row, by name: `status`, `held`,
+      #   `current`, `ordinal`, `move`, `reason` and `source` (`database`, or `none` for `no_eras`)
+      # @raise [Runtime::WiringError] if a binding cannot be resolved, a database is unreachable, or
+      #   a held text was altered
+      def rows(registry, directory)
+        registry.bluebooks.to_h { |name, bluebook| [name, row_for(registry, bluebook, directory)] }
+      end
+
+      # One bluebook's status row.
+      #
+      # @param registry [Runtime::Registry] the loaded registry
+      # @param bluebook [Bluebook::Declaration] the bluebook as it stands
+      # @param directory [String] the domain's bluebook directory
+      # @return [Hash] the row
+      def row_for(registry, bluebook, directory)
+        first = bluebook.aggregates.first
+        adapter = first && EraCheck.adapter_for(registry, bluebook.name, first)
+        return no_eras(bluebook, adapter || "nothing") unless adapter && EraCheck.lineage_capable?(registry, adapter)
+
+        settings = registry.binding_settings(bluebook.name, Ports::Persistence::VERB, adapter)
+        registry.adapter_class(adapter).era_status(registry: registry, bluebook: bluebook, settings: settings,
+                                                   directory: directory).to_row
+      end
+
+      # @param bluebook [Bluebook::Declaration] the bluebook
+      # @param adapter [String] the adapter it is bound to
+      # @return [Hash] the row of a bluebook whose store holds no eras
+      def no_eras(bluebook, adapter)
+        { "status" => "no_eras", "held" => nil, "current" => StorageShape.mint_label(bluebook), "ordinal" => nil,
+          "move" => nil, "reason" => "#{bluebook.name} is bound to #{adapter}, which holds no eras", "source" => "none" }
+      end
+    end
+  end
+end

data/lib/hecks/ports/persistence/plugins/era/era_tamper.rb

@@ -45,7 +45,7 @@ module Hecks
       # Parses the text from a tempfile that is removed afterwards.
       #
       # @param text [String] the bluebook source
-      # @return [Bluebook::Chapter, nil] the parsed bluebook; nil when the text declares none
+      # @return [Bluebook::Declaration, nil] the parsed bluebook; nil when the text declares none
       def parse_from_tempfile(text)
         file = Tempfile.new(["hecks-tamper-", ".bluebook"])
         file.write(text)