hecks 5.0.0 → 6.0.0

data/lib/hecks/ports/dispatch.rb

@@ -0,0 +1,28 @@
+require_relative "../runtime/errors"
+
+module Hecks
+  module Ports
+    # The `dispatch` port: who runs a domain's writes. Unbound, the boot's own `Dispatcher` does;
+    # a world's `dispatched_by("<Adapter>")` hands the job to that adapter, which answers
+    # `dispatcher(registry, settings)` with something of `Dispatcher`'s public shape.
+    module Dispatch
+      VERB = "dispatched_by".freeze
+
+      module_function
+
+      # Builds the dispatcher the world's `dispatched_by` binding names.
+      #
+      # @param registry [Runtime::Registry] the booted registry
+      # @param settings [Hash{Symbol => Object}] the binding: `:adapter` plus its declared settings
+      # @return [Object] the bound adapter's dispatcher
+      # @raise [Runtime::WiringError] if the adapter is unknown or cannot build a dispatcher
+      def dispatcher(registry, settings)
+        adapter = registry.adapter_class(settings[:adapter])
+        return adapter.dispatcher(registry, settings) if adapter.respond_to?(:dispatcher)
+
+        raise Runtime::WiringError,
+              "#{settings[:adapter]} cannot dispatch: it answers no `dispatcher` for `#{VERB}`"
+      end
+    end
+  end
+end

data/lib/hecks/ports/key_vault.rb

@@ -9,16 +9,20 @@ module Hecks
 
       module_function
 
-      # Mints a per-subject key; the key material itself never leaves the bound adapter.
+      # Mints a per-subject key; the key material itself never leaves the bound adapter. The
+      # `Keys` port's adapter calls it when a `SubjectKey` asks for a key (ADR 0147).
       def issue(registry, subject_id:) = adapter(registry).issue(subject_id: subject_id)
 
       # Irrevocably destroys a key; ciphertext under it becomes unrecoverable at once —
       # how a right-to-erasure request is satisfied without rewriting or deleting events.
       def destroy(registry, key_reference:) = adapter(registry).destroy(key_reference: key_reference)
 
-      # Destroys the subject's key, then dispatches Shred, in that fixed order — never the
-      # reverse, so Shred cannot be dispatched before the key is actually gone. Idempotent:
-      # a subject with no live key, or one already shredded, is left alone and returns false.
+      # Asks for the subject's key to be destroyed by dispatching Shred. The model keeps the
+      # order (ADR 0142): Shred only requests, the vault destroys the key, and the record reads
+      # `shredded` once the vault has answered. Idempotent: a subject with no key, or one already
+      # shredded or being shredded, is left alone and returns false.
+      #
+      # @return [Boolean] whether a shred was asked for; the record's status says how it ended
       def shred!(dispatcher, domain:, subject_id:) # rubocop:disable Naming/PredicateMethod
         provider = dispatcher.registry.provider_of(Bluebook::Capabilities::SUBJECT_KEYS)
         return false unless provider
@@ -26,9 +30,8 @@ module Hecks
         record = dispatcher.query(provider.provided_verb(Bluebook::Capabilities::SUBJECT_KEYS, :key_for),
                                   domain: domain, subject_id: subject_id).first
         return false unless record
-        return false if record[:status].to_s == "shredded"
+        return false if %w[shredded shredding].include?(record[:status].to_s)
 
-        destroy(dispatcher.registry, key_reference: record[:key_reference].value)
         shred = provider.provided_verb(Bluebook::Capabilities::SUBJECT_KEYS, :shred)
         dispatcher.dispatch_flat(shred, domain: { value: domain }, subject_id: { value: subject_id })
         true

data/lib/hecks/ports/loading.rb

@@ -1,20 +1,36 @@
-require_relative "../adapters/driven/folder"
+require_relative "../runtime/errors"
 
 module Hecks
   module Ports
-    # The `loading` port: `bootstrap` hands back the Folder adapter that
-    # reads bluebook files off disk to build the very first registry, before
-    # any other port has a registry to resolve against.
+    # The `loading` port: `bootstrap` hands back the adapter that reads bluebook files off disk to
+    # build the very first registry, before any other port has a registry to resolve against.
+    #
+    # The adapter registers itself here as it loads (`Adapters::Folder` does), so the port names
+    # no adapter of its own.
     module Loading
       NAME = "loading".freeze
 
+      @bootstrap = nil
+
       module_function
 
+      # Names the adapter class every boot starts loading with.
+      #
+      # @param adapter [Class] a class whose bare `.new` answers the loading port's methods
+      # @return [Class] the same class
+      def bootstrap_with(adapter)
+        @bootstrap = adapter
+      end
+
       # Builds the loader a boot starts from, before any registry exists to resolve one.
       #
-      # @return [Adapters::Folder] a new `Folder` adapter with no settings and no root,
-      #   constructed directly rather than resolved through a registry
-      def bootstrap = Adapters::Folder.new
+      # @return [Object] a new instance of the registered loading adapter, with no settings
+      # @raise [Runtime::WiringError] if no loading adapter has registered itself
+      def bootstrap
+        raise Runtime::WiringError, "no adapter has registered for the #{NAME} port" unless @bootstrap
+
+        @bootstrap.new
+      end
     end
   end
 end

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
@@ -26,6 +27,8 @@ module Hecks
       # 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.
@@ -323,13 +326,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
@@ -47,16 +89,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

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

@@ -3,9 +3,8 @@ require_relative "../../../../ports/persistence/binding_policy"
 require_relative "lineage"
 require_relative "../../../../naming"
 require_relative "../../../../framework"
-require_relative "../../../../chapters"
+require_relative "../../../../framework_bluebooks"
 require_relative "../../../../runtime/registry"
-require_relative "expected_era"
 
 module Hecks
   module Runtime
@@ -73,7 +72,7 @@ module Hecks
       # member or vendored bluebook is excluded from the single-file
       # fallback so its own real 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
@@ -101,10 +100,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 +115,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 +124,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 +134,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 +172,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 +197,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).

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_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)

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

@@ -10,7 +10,7 @@ module Hecks
 
       # Reduces a bluebook to the parts of its IR that decide what stored data looks like.
       #
-      # @param bluebook [Bluebook::Chapter] the bluebook whose `to_h` dump is projected
+      # @param bluebook [Bluebook::Declaration] the bluebook whose `to_h` dump is projected
       # @return [Hash{String => Object}] `"name"` (the bluebook's name) and `"aggregates"`, an
       #   Array of the Hashes `project_aggregate` builds, sorted by aggregate name
       def project(bluebook)
@@ -25,19 +25,19 @@ module Hecks
 
       # Compares two bluebooks by storage shape alone, ignoring every behavioral difference.
       #
-      # @param held [Bluebook::Chapter] the bluebook a held era was minted from
-      # @param current [Bluebook::Chapter] the bluebook booting now
+      # @param held [Bluebook::Declaration] the bluebook a held era was minted from
+      # @param current [Bluebook::Declaration] the bluebook booting now
       # @return [Boolean] true when both project to an equal structure
       def same?(held, current) = project(held) == project(current)
 
       # The canonical serialization hashed at mint time; stored era names are never recomputed.
-      # @param bluebook [Bluebook::Chapter] the bluebook to serialize
+      # @param bluebook [Bluebook::Declaration] the bluebook to serialize
       # @return [String] compact JSON text of `project(bluebook)`
       def canonical(bluebook) = JSON.generate(project(bluebook))
 
       # Computes the era identity of a bluebook's storage shape.
       #
-      # @param bluebook [Bluebook::Chapter] the bluebook being minted
+      # @param bluebook [Bluebook::Declaration] the bluebook being minted
       # @return [String] 64 lowercase hex characters, the SHA-256 of `canonical(bluebook)`
       def mint_hash(bluebook) = Digest::SHA256.hexdigest(canonical(bluebook))
 
@@ -45,7 +45,7 @@ module Hecks
 
       # Shortens the era identity to the label translation edges and refusals use.
       #
-      # @param bluebook [Bluebook::Chapter] the bluebook being minted
+      # @param bluebook [Bluebook::Declaration] the bluebook being minted
       # @return [String] the first `LABEL_LENGTH` hex characters of `mint_hash(bluebook)`
       def mint_label(bluebook) = mint_hash(bluebook)[0, LABEL_LENGTH]
 

data/lib/hecks/ports/persistence/plugins/era/translation/audit.rb

@@ -62,9 +62,15 @@ module Hecks
       def samples_for(declared, before, after)
         return rekeyed_samples(before, after) if declared && !declared.rekeys.empty?
 
-        before.keys.sort.first(SAMPLE_SIZE).map { |id| { id: id, before: before[id], after: after[id] } }
+        first_ids(before).map { |id| { id: id, before: before[id], after: after[id] } }
       end
 
+      # The ids a sample shows: the first `SAMPLE_SIZE`, in sorted order.
+      #
+      # @param states [Hash{String => Hash}] state per record id
+      # @return [Array<String>] up to `SAMPLE_SIZE` ids
+      def first_ids(states) = states.keys.sort.first(SAMPLE_SIZE)
+
       # Samples both sides of a rekeying edge separately, each labelled by its own id.
       #
       # A rekey changes the id, so pairing by id would show every `after` as nil.
@@ -74,8 +80,8 @@ module Hecks
       #   `" (before)"` with `:after` nil, then up to `SAMPLE_SIZE` ending in `" (after)"` with
       #   `:before` nil
       def rekeyed_samples(before, after)
-        before.keys.sort.first(SAMPLE_SIZE).map { |id| { id: "#{id} (before)", before: before[id], after: nil } } +
-          after.keys.sort.first(SAMPLE_SIZE).map { |id| { id: "#{id} (after)", before: nil, after: after[id] } }
+        first_ids(before).map { |id| { id: "#{id} (before)", before: before[id], after: nil } } +
+          first_ids(after).map { |id| { id: "#{id} (after)", before: nil, after: after[id] } }
       end
     end
   end

data/lib/hecks/ports/persistence/plugins/era/translation/reattest.rb

@@ -78,7 +78,7 @@ module Hecks
       # removed afterwards, without touching the live registry.
       #
       # @param source [String] bluebook source text
-      # @return [Bluebook::Chapter, nil] the first bluebook the source declares; nil when it
+      # @return [Bluebook::Declaration, nil] the first bluebook the source declares; nil when it
       #   declares none or fails to parse or load for any reason
       def shadow(source)
         file = Tempfile.new(["hecks-reattest-", ".bluebook"])