hecks 6.0.0 → 7.0.0

data/lib/hecks/language/kinds/run.kind

@@ -0,0 +1,120 @@
+# The Run kind: an aggregate declared `kind: "Run"` is one request to the codebase tooling, carried
+# out only inside a hecks checkout. It holds the lifecycle every such request shares, the three
+# bookkeeping commands that move it along, the two queries that read how requests ended, and the
+# policies that examine, accept, perform and record it.
+#
+# This file is aggregate-body text in the bluebook's own words. `{Name}` stands for the aggregate's
+# name and `{Stem}` for that name without the kind (`GateRun` has the stem `Gate`). The aggregate's
+# own body is evaluated at the `# body` line, so its attributes, value objects and request commands
+# fall between the lines above and below it.
+attribute :run,       RunKey
+attribute :operation, Operation, optional: true
+
+value_object "RunKey" do
+  attribute :value, String, matches: :present
+
+  invariant("a run is named") { !value.to_s.empty? }
+end
+
+value_object "Operation" do
+  attribute :value, String, matches: :present
+end
+
+value_object "Switch" do
+  attribute :value, Boolean
+end
+
+value_object "Report" do
+  attribute :value, String
+end
+
+# body
+
+attribute :checkout, Switch, optional: true
+attribute :report,   Report, optional: true
+attribute :refusal,  Report, optional: true
+identified_by :run
+
+lifecycle :status, default: "requested" do
+  mark :failure, "faulted"
+  transition "Accept"   => "accepted",  from: "requested"
+  transition "Complete" => "completed", from: "accepted"
+  transition "Fault"    => "faulted",   from: %w[requested accepted]
+  mark :terminal, "completed", "faulted"
+end
+
+# What the tree reported about itself, held against every request: nothing here runs
+# outside a hecks checkout (hecks.gemspec beside lib/).
+command "Accept" do
+  role "System"
+  goal "Let a request through only when the working tree is a hecks checkout"
+
+  reference_to {Name}
+  attribute :checkout, Switch, sets: true
+
+  given("needs a hecks checkout: hecks.gemspec stands beside lib/") { checkout.value }
+
+
+  emits {Stem}Accepted
+end
+
+command "Complete" do
+  role "System"
+  goal "Record that the request was carried out, and what it reported"
+
+  reference_to {Name}
+  attribute :report, Report, sets: true
+
+
+  emits {Stem}Completed
+end
+
+command "Fault" do
+  role "System"
+  goal "Record that the request was refused or could not be carried out, and why"
+
+  reference_to {Name}
+  attribute :refusal, Report, sets: true
+
+
+  emits {Stem}Faulted
+end
+
+query "{Stem}Outcome" do
+  description "How one request ended: its status, and what it reported or why it failed."
+  attribute :run, RunKey
+  where(run: :run)
+  order_by :run
+end
+
+query "{Stem}Faulted" do
+  description "Every request that was refused or could not be carried out."
+  where(status: "faulted")
+  order_by :run
+end
+
+policy "Accept{Stem}WhenExamined" do
+  on      "{Name}.{Stem}Examined"
+  trigger {Name}::Accept, with: { checkout: :checkout }
+end
+
+policy "Fault{Stem}WhenNotAccepted" do
+  on      "{Name}.{Stem}Examined"
+  where   { !checkout.value }
+  trigger {Name}::Fault, with: { refusal: "needs a hecks checkout: hecks.gemspec stands beside lib/" }
+end
+
+policy "Perform{Stem}WhenAccepted" do
+  on      "{Name}.{Stem}Accepted"
+  ask     :perform, with: { run: :run }
+end
+
+policy "Record{Stem}Outcome" do
+  on      "{Name}.{Stem}Answered"
+  trigger {Name}::Complete, with: { report: :report }
+end
+
+policy "Record{Stem}Fault" do
+  on      "{Name}.{Stem}Refused"
+  trigger {Name}::Fault, with: { refusal: :refusal }
+end

data/lib/hecks/language/oidc.json

@@ -81,6 +81,11 @@
       "verb": "Bluebook::Bluebook.Declare",
       "role": "Language"
     },
+    {
+      "scope": "bluebook:bluebook.group",
+      "verb": "Bluebook::Bluebook.Group",
+      "role": "Language"
+    },
     {
       "scope": "bluebook:bluebook.normalise",
       "verb": "Bluebook::Bluebook.Normalise",
@@ -96,6 +101,11 @@
       "verb": "Bluebook::Command.ActsOn",
       "role": "Language"
     },
+    {
+      "scope": "bluebook:command.address",
+      "verb": "Bluebook::Command.Address",
+      "role": "Language"
+    },
     {
       "scope": "bluebook:command.allow",
       "verb": "Bluebook::Command.Allow",

data/lib/hecks/language/translation/translation_aggregate.bluebook

@@ -31,6 +31,7 @@ Hecks.bluebook "Translation" do
     attribute :retypes,   list_of(TranslationRetype)
     attribute :derives,   list_of(TranslationDerive)
     attribute :rekeys,    list_of(TranslationRekey)
+    attribute :splits,    list_of(TranslationSplit)
     attribute :backfills, list_of(TranslationBackfill)
 
     # Field names mirror the Struct records in lib/hecks/bluebook/translation.rb, not the
@@ -65,6 +66,12 @@ Hecks.bluebook "Translation" do
       attribute :to, TranslationName
     end
 
+    value_object "TranslationSplit" do
+      attribute :into,     TranslationName
+      attribute :keyed_by, TranslationName
+      attribute :fields,   list_of(TranslationName)
+    end
+
     value_object "TranslationBackfill" do
       attribute :name,    TranslationName
       attribute :default, TranslationLiteralText
@@ -168,6 +175,19 @@ Hecks.bluebook "Translation" do
       emits "TranslationRekeyToAdded"
     end
 
+    command "AddSplit" do
+      role "Deployment"
+      goal "Write rows into another aggregate from this one's rows, keyed by a field both share"
+
+      attribute :into,     TranslationName
+      attribute :keyed_by, TranslationName
+      attribute :fields,   list_of(TranslationName)
+
+      sets :splits, append: { into: :into, keyed_by: :keyed_by, fields: :fields }
+
+      emits "TranslationSplitAdded"
+    end
+
     command "AddBackfill" do
       role "Deployment"
       goal "Name a newly required attribute and the value an existing record reads until written for real"
@@ -194,6 +214,7 @@ Hecks.bluebook "Translation" do
       attribute :disambiguator, String, default: "", admits: "Syntax::Disambiguator"
 
       member word: "rename",          context: "TranslationAggregate", body: "none", inner: "", opens: "", fills: "renames", calls: "rename_impl"
+      member word: "split",            context: "TranslationAggregate", body: "none", inner: "", opens: "", fills: "splits", calls: "split_impl"
       member word: "move",            context: "TranslationAggregate", body: "none", inner: "", opens: "", fills: "moves", calls: "move_impl"
       member word: "convert",         context: "TranslationAggregate", body: "none", inner: "", opens: "", fills: "converts", calls: "convert_impl"
       member word: "drop",            context: "TranslationAggregate", body: "none", inner: "", opens: "", fills: "drops"
@@ -224,6 +245,9 @@ Hecks.bluebook "Translation" do
 
       member keyword: "rename",          context: "TranslationAggregate", at: "1", named: "", kind: "symbol", required: "true", fills: "old_name"
       member keyword: "rename",          context: "TranslationAggregate", at: "",  named: "to", kind: "symbol", required: "true", fills: "to"
+      member keyword: "split",            context: "TranslationAggregate", at: "",  named: "into", kind: "text", required: "true", fills: "into"
+      member keyword: "split",            context: "TranslationAggregate", at: "",  named: "keyed_by", kind: "text", required: "true", fills: "keyed_by"
+      member keyword: "split",            context: "TranslationAggregate", at: "",  named: "fields", kind: "text", required: "true", fills: "fields"
       member keyword: "move",            context: "TranslationAggregate", at: "1", named: "", kind: "text", required: "true", fills: "old_path"
       member keyword: "move",            context: "TranslationAggregate", at: "",  named: "to", kind: "text", required: "true", fills: "to"
       member keyword: "convert",         context: "TranslationAggregate", at: "1", named: "", kind: "text", required: "true", fills: "old_path"

data/lib/hecks/module_folders.rb

@@ -0,0 +1,31 @@
+module Hecks
+  # The module folders of a domain directory (ADR 0163). A folder named for a module holds that
+  # module's bluebook beside its name, `deliver/deliver.bluebook`; the bluebooks in them declare
+  # the one bluebook the directory's top-level file opens.
+  module ModuleFolders
+    module_function
+
+    # @param directory [String] a domain directory
+    # @return [Array<String>] the bluebook of each module folder directly under `directory`,
+    #   sorted by path
+    def bluebooks(directory)
+      files(directory, ".bluebook")
+    end
+
+    def files(directory, extension)
+      Dir.glob(File.join(directory, "*", "*#{extension}")).select { |path| module_file?(path, extension) }.sort
+    end
+
+    # @param directory [String] a domain directory
+    # @return [Array<String>] the directory's own bluebooks, then those of its module folders
+    def all(directory)
+      Dir.glob(File.join(directory, "*.bluebook")) + bluebooks(directory)
+    end
+
+    # Whether a bluebook is named for the folder it sits in.
+    # @api private
+    def module_file?(path, extension)
+      File.basename(path, extension) == File.basename(File.dirname(path))
+    end
+  end
+end

data/lib/hecks/ports/key_vault.rb

@@ -23,7 +23,7 @@ module Hecks
       # 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
+      def shred!(dispatcher, domain:, subject_id:)
         provider = dispatcher.registry.provider_of(Bluebook::Capabilities::SUBJECT_KEYS)
         return false unless provider
 

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

@@ -12,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"`
@@ -22,6 +26,9 @@ 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
@@ -49,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`
@@ -183,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)
@@ -208,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
@@ -231,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)

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

@@ -80,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

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

@@ -83,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

@@ -4,6 +4,7 @@ require_relative "lineage"
 require_relative "../../../../naming"
 require_relative "../../../../framework"
 require_relative "../../../../framework_bluebooks"
+require_relative "../../../../module_folders"
 require_relative "../../../../runtime/registry"
 
 module Hecks
@@ -67,10 +68,10 @@ 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::Declaration] the bluebook whose source is wanted
       # @param directory [String] path of the domain's own bluebook directory
@@ -78,7 +79,7 @@ module Hecks
       # @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?
 

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

@@ -68,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_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/projected_bluebook.rb

@@ -0,0 +1,127 @@
+require "digest"
+require "json"
+
+module Hecks
+  module Runtime
+    # A held era read from the storage shape its mint recorded, answering the bluebook questions an
+    # era's diff, additive rule and coverage check ask of the side they translate from: each
+    # aggregate's name, identity paths and attributes, and each value object's members.
+    #
+    # The shape is what an era is: its hash is the SHA-256 of the shape's canonical JSON, the same
+    # one `StorageShape.mint_hash` takes of a declared bluebook. Nothing here parses held text.
+    class ProjectedBluebook
+      # One attribute or value-object member, by name and type name. The name is a Symbol and the
+      # type name a String, as a declared bluebook answers them.
+      Attribute = Data.define(:name, :type, :list) do
+        # @return [Boolean] whether the attribute holds a list
+        def list? = list
+      end
+
+      # A value object or entity an attribute's type names, with its members.
+      Container = Data.define(:name, :attributes) do
+        # @param name [String, Symbol] a member name
+        # @return [Attribute, nil] the member of that name
+        def attribute(name) = attributes.find { |member| member.name.to_s == name.to_s }
+      end
+
+      # One aggregate of the held shape.
+      class Aggregate
+        attr_reader :name, :identity_paths, :attributes
+
+        # @param shape [Hash{String => Object}] one entry of the projection's `aggregates`
+        def initialize(shape)
+          @name = shape["name"]
+          @identity_paths = Array(shape["identity"])
+          @containers = {}
+          @attributes = Array(shape["attributes"]).map { |attribute| read(attribute) }
+        end
+
+        # @param name [String, Symbol] an attribute name
+        # @return [Attribute, nil] the attribute of that name
+        def attribute(name) = attributes.find { |attribute| attribute.name.to_s == name.to_s }
+
+        # @param type_name [String] a type name an attribute or member names
+        # @return [Container, nil] the value object or entity of that name
+        def value_object(type_name) = @containers[type_name]
+
+        # @return [Array] none: entities are answered as containers by `value_object`
+        def entities = []
+
+        private
+
+        # Reads one attribute or member, keeping the container its type expands to.
+        def read(attribute)
+          type = attribute["type"]
+          type = contain(type) if type.is_a?(Hash)
+          Attribute.new(name: attribute["name"].to_sym, type: type, list: attribute["list"] == true)
+        end
+
+        # Keeps the value object or entity a type expands to, and answers its name.
+        def contain(type)
+          name = type["type"]
+          @containers[name] ||= Container.new(name: name, attributes: Array(type["members"]).map { |member| read(member) })
+          name
+        end
+      end
+
+      attr_reader :projection, :name, :aggregates
+
+      # @param projection [Hash{String => Object}] a storage shape, as `StorageShape.project`
+      #   answers it or as `hecks_eras.held_projection` stores it
+      def initialize(projection)
+        @projection = projection
+        @name = projection["name"]
+        @aggregates = Array(projection["aggregates"]).map { |shape| Aggregate.new(shape) }
+      end
+
+      # @param projection_or_bluebook [Hash, ProjectedBluebook, Object] a storage shape, a view, or
+      #   a declared bluebook
+      # @return [ProjectedBluebook, Object] a storage shape wrapped as a view; anything else as
+      #   given
+      def self.wrap(projection_or_bluebook)
+        projection_or_bluebook.is_a?(Hash) ? new(projection_or_bluebook) : projection_or_bluebook
+      end
+
+      # @param name [String, Symbol] an aggregate name
+      # @return [Aggregate, nil] the aggregate of that name
+      def aggregate(name) = aggregates.find { |aggregate| aggregate.name == name.to_s }
+
+      # @return [nil] a held shape carries no rename marker; the declared bluebook does
+      def formerly_known_as = nil
+
+      # @return [String] the era's hash: the SHA-256 of the shape's canonical JSON
+      def mint_hash = Digest::SHA256.hexdigest(JSON.generate(Canonical.shape(projection)))
+
+      # The storage shape with its keys in the order `StorageShape.project` builds them, so a shape
+      # read back from `jsonb`, which reorders keys, hashes as it did when it was minted.
+      module Canonical
+        module_function
+
+        # @param shape [Hash] a storage shape
+        # @return [Hash] the shape with its keys in canonical order
+        def shape(shape)
+          { "name" => shape["name"], "aggregates" => Array(shape["aggregates"]).map { |aggregate| aggregate(aggregate) } }
+        end
+
+        # @return [Hash] one aggregate's shape in canonical key order
+        def aggregate(aggregate)
+          { "name" => aggregate["name"], "identity" => aggregate["identity"],
+            "lifecycle_field" => aggregate["lifecycle_field"],
+            "attributes" => Array(aggregate["attributes"]).map { |attribute| attribute(attribute) } }
+        end
+
+        # @return [Hash] one attribute's shape in canonical key order
+        def attribute(attribute)
+          { "name" => attribute["name"], "list" => attribute["list"], "type" => type(attribute["type"]) }
+        end
+
+        # @return [String, Hash] a scalar type as given, or a container in canonical key order
+        def type(type)
+          return type unless type.is_a?(Hash)
+
+          { "type" => type["type"], "members" => Array(type["members"]).map { |member| attribute(member) } }
+        end
+      end
+    end
+  end
+end