hecks 6.0.0 → 7.0.0

data/lib/hecks/adapters/driving/write_guard.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "context_line"
+require_relative "../driven/worktree_overlay"
+
+module Hecks
+  module Adapters
+    module Driving
+      # Refuses a write from a linked worktree whose bluebook would store in Memory there while the
+      # main checkout stores it elsewhere. It asks the same overlay question the worktree warning
+      # asks (WorktreeOverlay.gap), and reads stores the way `hecks config` does, so the refusal
+      # and the warning cannot disagree about what is missing.
+      module WriteGuard
+        module_function
+
+        # @param directory [String] the checkout the command runs in
+        # @param bluebook [String, nil] the bluebook the command belongs to
+        # @param stores [#call] answers the store rows of a directory
+        # @return [String, nil] the refusal, or nil when the write may proceed
+        def refusal(directory, bluebook, stores: STORES)
+          return unless bluebook
+
+          main, files = WorktreeOverlay.gap(directory)
+          return if files.empty?
+
+          main_kind = kind_in(stores.call(main), bluebook)
+          return if main_kind == ContextLine::MEMORY || main_kind == kind_in(stores.call(directory), bluebook)
+
+          message(bluebook, main_kind, files)
+        end
+
+        # @param rows [Array<Array(String, String, String)>] store rows
+        # @param bluebook [String]
+        # @return [String] the kind of store the bluebook uses, Memory when it has none of its own
+        def kind_in(rows, bluebook)
+          row = rows.find { |label, _value, _source| label == "store #{bluebook}" }
+          ContextLine.kind(row ? row[1] : ContextLine::MEMORY)
+        end
+
+        # @return [String] the refusal naming the bluebook, the store and the missing files
+        def message(bluebook, main_kind, files)
+          "hecks: refused: #{bluebook} stores in #{main_kind} in the main checkout, and this worktree " \
+            "lacks #{files.join(", ")}, so the write would land in Memory here. " \
+            "Run the command from the main checkout."
+        end
+
+        # Answers the store rows of a directory, through the adapter `hecks config` uses.
+        STORES = lambda do |directory|
+          require_relative "../../hecks/adapters/settings_reading"
+          Hecks::Adapters::SettingsReading.new.stores(directory)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driving.rb

@@ -10,7 +10,6 @@ module Hecks
   # A constant owned by user code or the stdlib is left alone with a warning.
   module Namespace
     # A live registry, mutated by `install`, so it cannot be frozen.
-    # rubocop:disable-next Style/MutableConstant
     GENERATED = {}
 
     module_function

data/lib/hecks/behaviors/dsl.rb

@@ -1,4 +1,5 @@
 require_relative "ir"
+require_relative "../module_folders"
 
 # The authoring surface for `Hecks.behaviors "Name" do ... end`, built with `instance_eval`.
 module Hecks
@@ -132,9 +133,12 @@ module Hecks
       #
       # @param paths [Array<String>] paths to the files this suite's domain boots
       #   from, relative to the `.behaviors` file
+      # @param modules [Symbol, nil] `:all` adds the bluebook of every module folder beside the
+      #   `.behaviors` file (see ModuleFolders)
       # @return [void]
-      def loads(*paths)
+      def loads(*paths, modules: nil)
         @loads = paths.map { |path| File.expand_path(path, @source_dir) }
+        @loads.concat(ModuleFolders.bluebooks(@source_dir)) if modules == :all
       end
 
       # Builds and records one test case.

data/lib/hecks/behaviors/expectations/boot.rb

@@ -12,7 +12,6 @@ module Hecks
         # Cached per suite, keyed by `loads`' file paths and mtimes, so a boot is
         # reused across tests but an edited bluebook boots fresh on the next one.
         # Mutated in place (`RUNTIMES[key] ||= boot_and_guard(files)`).
-        # rubocop:disable-next Style/MutableConstant
         RUNTIMES      = {}
         RUNTIMES_LOCK = Mutex.new
         private_constant :RUNTIMES, :RUNTIMES_LOCK

data/lib/hecks/bluebook/acknowledgements.rb

@@ -4,7 +4,7 @@ module Hecks
     # reason, and a kind the check really emits (ADR 0150).
     module Acknowledgements
       # The finding kinds an aggregate may acknowledge.
-      AGGREGATE_KINDS = %i[large_aggregate key_by_value orphaned_reference].freeze
+      AGGREGATE_KINDS = %i[large_aggregate key_by_value orphaned_reference no_command_surface].freeze
 
       # The kinds that are reported once per attribute or per referenced aggregate, so an
       # acknowledgement of one names which (`of:`): the attribute for `key_by_value`, the

data/lib/hecks/bluebook/aggregate.rb

@@ -20,44 +20,47 @@ module Hecks
       include Behaviour::Aggregate
 
       emits_ir(
-        name:             :name,
-        description:      :description,
-        identified_by:    :identity_paths,
-        attributes:       many(:attributes),
-        value_objects:    many(:value_objects),
-        commands:         many(:commands),
-        invariants:       -> { invariants.map { |rule| Expression::AstJson.rule_row(rule) } },
+        name:              :name,
+        description:       :description,
+        identified_by:     :identity_paths,
+        attributes:        many(:attributes),
+        value_objects:     many(:value_objects),
+        commands:          many(:commands),
+        invariants:        -> { invariants.map { |rule| Expression::AstJson.rule_row(rule) } },
         # The named `given`s a referencing command's resolved `givens` entry came from.
-        preconditions:    -> { preconditions.map { |rule| Expression::AstJson.rule_row(rule) } },
+        preconditions:     -> { preconditions.map { |rule| Expression::AstJson.rule_row(rule) } },
         # Not folded into `attributes`: EraGuard::ShapeDiff walks those, and a record predating
         # `projects` is expected to lack this field until the rebuild sweep runs.
-        projected_fields: lambda {
+        projected_fields:  lambda {
           projected_fields.map do |field|
             { name: field.name.to_s, reference: field.reference.to_s, remote_field: field.remote_field.to_s }
           end
         },
-        lifecycle:        one(:lifecycle),
-        entities:         many(:entities),
-        queries:          many(:queries),
+        lifecycle:         one(:lifecycle),
+        entities:          many(:entities),
+        queries:           many(:queries),
         # Additive: domains that declare no port emit `ports: []`; no existing key moves.
-        ports:            many(:ports),
-        provenance:       :provenance,
+        ports:             many(:ports),
+        provenance:        :provenance,
+        formerly_known_as: :formerly_known_as,
+        created_by:        :created_by,
         # Additive: an aggregate that acknowledges no finding emits `acknowledgements: []`.
-        acknowledgements: lambda {
-          acknowledgements.map { |held| { finding: held.finding.to_s, subject: held.subject.to_s, reason: held.reason } }
+        acknowledgements:  lambda {
+          acknowledgements.map { |held| { finding: held.finding.to_s, subject: held.subject, reason: held.reason } }
         }
       )
 
       attr_reader :name, :description, :attributes, :value_objects, :commands, :invariants, :preconditions,
                   :projected_fields, :identified_by, :identity_paths, :identity_heads, :lifecycle,
                   :entities, :queries, :policies, :ports, :reference_targets, :provenance,
-                  :acknowledgements
+                  :acknowledgements, :formerly_known_as, :created_by
 
       # Every optional field and what it holds when the declaration omits it.
       FIELD_DEFAULTS = {
         description: nil, attributes: [], value_objects: [], commands: [], invariants: [],
         preconditions: [], projected_fields: [], identified_by: [], lifecycle: nil, entities: [],
-        queries: [], policies: [], ports: [], reference_targets: [], provenance: nil, acknowledgements: []
+        queries: [], policies: [], ports: [], reference_targets: [], provenance: nil, acknowledgements: [],
+        formerly_known_as: nil, created_by: nil
       }.freeze
 
       # Assigns the declared fields, then `settle` derives identity, name indexes and owner stamps.

data/lib/hecks/bluebook/assembly/contracts/sagas.rb

@@ -13,6 +13,8 @@ module Hecks
             correlates_by: [:correlates_by, :identity],
             starts_on:     [:starts_on,     :plain],
             ends_on:       [:ends_on,       :plain],
+            endings:       [:endings,       :plain],
+            resumes:       [:resumes,       :plain],
             states:        [:states,        :plain]
           },
           reads: { states: :names },

data/lib/hecks/bluebook/assembly/contracts/structure.rb

@@ -14,7 +14,8 @@ module Hecks
             formerly_known_as: [:formerly_known_as, :plain],
             namespace:         [:namespace, :plain],
             attaches_to:       [:attaches_to, :plain],
-            provides:          [:provides, :plain]
+            provides:          [:provides, :plain],
+            modules:           [:modules, :plain]
           },
           rows: { normalisations: :normalisation_table },
           derived: { normalisations: :elsewhere }
@@ -23,17 +24,19 @@ module Hecks
         "Aggregate"   => Contract.new(
           holder: Aggregate, make: :new,
           fields: {
-            name:             [:name,          :plain],
-            description:      [:description,   :plain],
-            identified_by:    [:identified_by, :plain],
-            attributes:       [:attributes,    [:each, :attribute]],
+            name:              [:name,          :plain],
+            description:       [:description,   :plain],
+            identified_by:     [:identified_by, :plain],
+            attributes:        [:attributes,    [:each, :attribute]],
             # Aggregate's own precondition, referenced by name from a command (ADR 0025).
-            invariants:       [:invariants,    [:each, :invariant]],
-            preconditions:    [:preconditions, [:each, :given]],
+            invariants:        [:invariants,    [:each, :invariant]],
+            preconditions:     [:preconditions, [:each, :given]],
             # The local half of `projects :name, from: "reference.remote_field"` (ADR 0025).
-            projected_fields: [:projected_fields, [:each, :projected_field]],
-            provenance:       [:provenance, :plain],
-            acknowledgements: [:acknowledgements, [:each, :acknowledgement]]
+            projected_fields:  [:projected_fields, [:each, :projected_field]],
+            provenance:        [:provenance, :plain],
+            formerly_known_as: [:formerly_known_as, :plain],
+            created_by:        [:created_by, :plain],
+            acknowledgements:  [:acknowledgements, [:each, :acknowledgement]]
           },
           rows: { transitions: :transition_rows, marks: :mark_rows, value_objects: :value_object_names,
                   identified_by: :identity_rows },
@@ -56,6 +59,7 @@ module Hecks
             name:       [:name,       :plain],
             role:       [:role,       :plain],
             roles:      [:roles,      :plain],
+            audience:   [:audience,   :plain],
             goal:       [:goal,       :plain],
             references: [:references, :plain],
             attributes: [:attributes, [:each, :shape_field]],
@@ -67,13 +71,14 @@ module Hecks
             # Lifecycle state as a command guard: one state, an array, or nil (ADR 0025).
             from:       [:from,       :plain],
             provenance: [:provenance, :plain],
-            idempotent: [:idempotent, :plain]
+            idempotent: [:idempotent, :plain],
+            mints_era:  [:mints_era, :plain]
           },
           rows: { mutations: :mutation_rows },
           reads: { attributes: [:each, :shape_field], givens: [:each, :rule], ensures: [:each, :rule],
-                  needs: [:each, :need], mutations: [:call, :mutations], emits: :names, roles: :names,
+                  needs: [:each, :need], mutations: [:call, :mutations], emits: :names, roles: :names, audience: :names,
                   provenance: :provenance,
-                  from: :from, idempotent: :idempotent? },
+                  from: :from, idempotent: :idempotent?, mints_era: :mints_era? },
           derived: { position: :walk }
         ),
 

data/lib/hecks/bluebook/behaviour/aggregate.rb

@@ -112,11 +112,35 @@ module Hecks
           @ports_by_name[port.name] = port
         end
 
+        # The physical name the world gives this aggregate (`stored_as Revision: "commit"`), set
+        # when a registry applies its world's names. Nothing in the bluebook sets it.
+        attr_writer :stored_as, :prior_storage_names
+
         # Names the table, file or key persistence adapters store this aggregate
-        # under.
+        # under. A renamed aggregate keeps the name its rows were written under, so
+        # its stored records stay where they are.
+        #
+        # @return [String] the world's `stored_as` when it gives one, else the former name from
+        #   `formerly_known_as` when the bluebook declares one, else the aggregate's own name,
+        #   snake-cased
+        def storage_name = Naming.snake(@stored_as || former_name || @name)
+
+        # The physical names this aggregate's rows may sit under from an earlier name: its
+        # `formerly_known_as` and every name a translation edge renames it from. An adapter
+        # that finds rows under one while its own table is empty refuses instead of beginning anew.
         #
-        # @return [String] the aggregate's name, snake-cased
-        def storage_name = Naming.snake(@name)
+        # @return [Array<String>] snake-cased names other than the current storage name
+        def prior_storage_names = (@prior_storage_names || []).map { |name| Naming.snake(name) } - [storage_name]
+
+        # The name this aggregate carried before its rename, from `formerly_known_as`.
+        #
+        # @return [String, nil] the former name, or nil when the aggregate was never renamed
+        def former_name
+          held = formerly_known_as
+          return nil if held.nil?
+
+          (held.respond_to?(:value) ? held.value : held).to_s
+        end
       end
     end
   end

data/lib/hecks/bluebook/command.rb

@@ -52,6 +52,8 @@ module Hecks
         role:       :role,
         # Every role that may run the command, when more than one may; `role` is then the first.
         roles:      -> { roles.size > 1 ? roles : Hecks::IR::OMIT },
+        # Who a launcher lists the command for; absent when the command declares none.
+        audience:   -> { audience.empty? ? Hecks::IR::OMIT : audience },
         goal:       :goal,
         references: :references,
         attributes: many(:attributes),
@@ -64,29 +66,38 @@ module Hecks
         from:       -> { from },
         provenance: :provenance,
         # Safe to deliver twice; the saga redrive reads it for a dispatch left unsettled.
-        idempotent: -> { idempotent? }
+        idempotent: -> { idempotent? },
+        # Lets this command's own record through a boot whose shape no era holds yet.
+        mints_era:  -> { mints_era? }
       )
 
       # Every optional declared field and what it holds when the declaration omits it.
       FIELD_DEFAULTS = {
-        role: nil, roles: [], goal: nil, attributes: [], givens: [], ensures: [], needs: [],
-        mutations: [], emits: [], references: nil, from: nil, provenance: nil, idempotent: false
+        role: nil, roles: [], audience: [], goal: nil, attributes: [], givens: [], ensures: [], needs: [],
+        mutations: [], emits: [], references: nil, from: nil, provenance: nil, idempotent: false,
+        mints_era: false
       }.freeze
 
       class << self
         attr_reader :role, :goal, :attributes, :givens, :ensures, :needs, :mutations, :emits, :references,
-                    :from, :provenance, :idempotent
+                    :from, :provenance, :idempotent, :mints_era
 
         # @return [Boolean] whether a second delivery leaves the state a first one did
         def idempotent? = @idempotent ? true : false
 
+        # @return [Boolean] whether this command's own record may be written through an unminted boot
+        def mints_era? = @mints_era ? true : false
+
         # @return [Array<String>] every role that may run it when more than one may, else empty
         def roles = @roles || []
 
+        # @return [Array<String>] who a launcher lists it for, else empty (a person and an agent)
+        def audience = @audience || []
+
         # Mints one command as its own anonymous subclass of the class `declare` is called on.
         #
         # @param name [String, Symbol] the command's declared name
-        # @param role [String, nil] the declared role; `roles` all of them when several may run it
+        # @param role [String, nil] the declared role; `roles` all of them, `audience` who it is listed for
         # @param attributes [Array<Bluebook::Attribute>] the declared arguments
         # @param givens [Array<Bluebook::Given>] the declared preconditions
         # @param ensures [Array<Bluebook::Given>] the postconditions; `needs` the facts it supplies

data/lib/hecks/bluebook/declaration.rb

@@ -36,6 +36,9 @@ module Hecks
         # One row per declared `provides` capability, in declaration order;
         # present (possibly empty) like `attaches_to`.
         provides:          -> { provides.map(&:to_h) },
+        # One row per aggregate a module groups, in declaration order; left out when the bluebook
+        # declares no module, so a bluebook that never groups emits as it did.
+        modules:           -> { modules.empty? ? Hecks::IR::OMIT : modules.map(&:to_h) },
         canonical_form:    -> { Expression::CanonicalForm.table }
       )
 
@@ -56,14 +59,32 @@ module Hecks
         end
       end
 
+      # One aggregate's membership of a module: the module's name and vision, and the aggregate.
+      ModuleRow = Struct.new(:name, :vision, :aggregate, keyword_init: true) do
+        # Coerces one declared or reconstructed module row into a `ModuleRow`.
+        #
+        # @param row [Bluebook::Declaration::ModuleRow, #to_h] a `ModuleRow` already, or anything
+        #   answering `to_h` with `name`/`vision`/`aggregate` entries
+        # @return [Bluebook::Declaration::ModuleRow] `row` itself if it already is one, else a new one
+        def self.from(row)
+          return row if row.is_a?(self)
+
+          fields = row.to_h.transform_keys(&:to_sym)
+          new(name: fields[:name].to_s, vision: fields[:vision].to_s, aggregate: fields[:aggregate].to_s)
+        end
+      end
+
+      attr_accessor :formerly_known_as
+
       attr_reader :name, :version, :vision, :aggregates, :policies, :process_managers,
-                  :classification, :read_models, :ports, :formerly_known_as, :namespace, :attaches_to, :provides
+                  :classification, :read_models, :ports, :namespace, :attaches_to, :provides,
+                  :modules
 
       # Every optional field and what it holds when the declaration omits it.
       FIELD_DEFAULTS = {
         version: nil, vision: nil, aggregates: [], policies: [], process_managers: [],
         classification: nil, read_models: [], formerly_known_as: nil, namespace: nil,
-        attaches_to: [], provides: []
+        attaches_to: [], provides: [], modules: []
       }.freeze
 
       # @param policies [Array<Bluebook::Policy>] every reaction declared across the
@@ -85,10 +106,17 @@ module Hecks
         @classification    = @classification&.to_s
         @formerly_known_as = @formerly_known_as&.to_s
         @namespace         = @namespace&.to_s
-        @attaches_to       = Array(@attaches_to).map(&:to_s)
-        @provides          = Array(@provides).map { |row| Provision.from(row) }
+        coerce_rows
       end
       private :coerce_fields
+
+      # Holds every row-valued field as the rows its reader answers.
+      def coerce_rows
+        @attaches_to = Array(@attaches_to).map(&:to_s)
+        @provides    = Array(@provides).map { |row| Provision.from(row) }
+        @modules     = Array(@modules).map { |row| ModuleRow.from(row) }
+      end
+      private :coerce_rows
     end
   end
 end

data/lib/hecks/bluebook/domain_port.rb

@@ -10,9 +10,12 @@ module Hecks
       include Hecks::IR
       include Behaviour::PortOperation
 
-      emits_ir(name: :hecks_name, attributes: many(:attributes), emits: :emits)
+      emits_ir(
+        name: :hecks_name, attributes: many(:attributes), emits: :emits,
+        handles: -> { handles.map { |held| { command: held[:command], value: held[:value] } } }
+      )
 
-      attr_reader :hecks_name, :attributes, :emits, :direction, :answers, :refuses, :to
+      attr_reader :hecks_name, :attributes, :emits, :direction, :answers, :refuses, :to, :handles
 
       # Marks this operation as the one the hecksagon picks (`ask_via`) when its ask name is
       # declared on more than one port of the aggregate.
@@ -29,7 +32,8 @@ module Hecks
       #
       # Every optional keyword and what it holds when the declaration omits it.
       FIELD_DEFAULTS = {
-        attributes: [], emits: [], direction: :inbound, answers: nil, refuses: nil, to: nil, chosen: false
+        attributes: [], emits: [], direction: :inbound, answers: nil, refuses: nil, to: nil, chosen: false,
+        handles: []
       }.freeze
 
       # @param name [String, Symbol] the operation's declared name

data/lib/hecks/bluebook/dsl/aggregate_builder/relationships.rb

@@ -65,7 +65,6 @@ module Hecks
 
         # `has_many_impl`/`has_one_impl` are DSL keywords (`has_many`/`has_one` in a bluebook),
         # not real predicates, so Naming/PredicatePrefix does not apply here.
-        # rubocop:disable Naming/PredicatePrefix
 
         # Declares a list-typed relationship to another aggregate, referenced by its plural name.
         #
@@ -105,7 +104,6 @@ module Hecks
           relationship_attribute(target, :has_one, as || Naming.snake(target).to_sym,
                                  optional: optional)
         end
-        # rubocop:enable Naming/PredicatePrefix
 
         # Declares a single-valued relationship toward the aggregate that owns this one.
         #

data/lib/hecks/bluebook/dsl/aggregate_builder/renaming.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Bluebook
+    module DSL
+      class AggregateBuilder
+        # The names an aggregate keeps: the name it held before a rename, which keeps the old name
+        # resolving, and the command that creates its records, which a missing-record refusal names.
+        module Renaming
+          # @param value [Object] the name the aggregate held before, as the attribute types it
+          # @return [Object] the old name as stored
+          def formerly_known_as_impl(value)
+            @formerly_known_as = value
+          end
+
+          # @param value [Object] the command's name, as the bluebook writes it (e.g. "Adr.draft!")
+          # @return [Object] the command name as stored
+          def created_by_impl(value)
+            @created_by = value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/dsl/aggregate_builder.rb

@@ -4,6 +4,7 @@ require_relative "aggregate_builder/relationships"
 require_relative "aggregate_builder/one_of_reference"
 require_relative "aggregate_builder/rules"
 require_relative "aggregate_builder/draining"
+require_relative "aggregate_builder/renaming"
 module Hecks
   module Bluebook
     module DSL
@@ -17,6 +18,7 @@ module Hecks
         include RuleReference
         include WordGate
         include Sealing
+        include Renaming
         include OneOfReference
 
         # @param name [String] the aggregate's name, as written after `aggregate`
@@ -177,6 +179,7 @@ module Hecks
           { name: @name, description: @description, attributes: attributes,
             value_objects: @value_objects + closed_sets, identified_by: @identity_paths,
             lifecycle: @lifecycle, entities: @entities, provenance: @provenance,
+            formerly_known_as: @formerly_known_as, created_by: @created_by,
             acknowledgements: @acknowledgements }
         end
 

data/lib/hecks/bluebook/dsl/attribute_collector.rb

@@ -10,7 +10,6 @@ module Hecks
 
         ListOf = Struct.new(:type)
         # `:values` shadows Struct#values so the accessor returns the flat permitted-value array.
-        # rubocop:disable-next Lint/StructNewOverride
         OneOf  = Struct.new(:values)
 
         UNSET = Object.new.freeze

data/lib/hecks/bluebook/dsl/audience_word.rb

@@ -0,0 +1,40 @@
+module Hecks
+  module Bluebook
+    module DSL
+      # The `audience` word of a command: who a launcher lists it for (ADR 0163). It decides
+      # listing only; the role still decides who may run the command. The including builder holds
+      # `@name`.
+      module AudienceWord
+        # The audiences a command may be listed for: a person at a keyboard, an agent through the
+        # MCP door, a CI step, or the run's own bookkeeping.
+        AUDIENCES = %w[person agent ci record].freeze
+
+        # Names who a launcher lists the command for.
+        #
+        # @param values [Array<Symbol, String>] one or several of `AUDIENCES`
+        # @return [Array<String>] the audience as stored
+        # @raise [Bluebook::DSL::Malformed] if one is already declared, one is not an audience, or
+        #   one is named twice
+        def audience_impl(*values)
+          names = values.map(&:to_s)
+          raise Malformed, "#{@name} declares its audience twice" if @audience
+          raise Malformed, audience_problem(names) if audience_problem(names)
+
+          @audience = names
+        end
+
+        private
+
+        # Why an audience declaration is refused, or nil when every name is an audience named once.
+        def audience_problem(names)
+          return "#{@name} names no audience" if names.empty?
+
+          unknown = names - AUDIENCES
+          return "#{@name} names #{unknown.join(", ")} as an audience; the audiences are #{AUDIENCES.join(", ")}" if unknown.any?
+
+          "#{@name} names an audience twice" if names.uniq.size != names.size
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/dsl/bluebook_builder/metadata.rb

@@ -0,0 +1,56 @@
+module Hecks
+  module Bluebook
+    module DSL
+      class BluebookBuilder
+        # The words that describe the whole bluebook rather than one construct in it: its earlier
+        # name, the Ruby module its constants install under, and its classification. Each refuses
+        # to sit inside a `domain_module` block, since a module names a task, not the bluebook.
+        module Metadata
+          # Records the bluebook's earlier name, so the storage layer recognizes its history
+          # under it instead of minting a new lineage — a bluebook's identity can change.
+          #
+          # @param value [String, Symbol] the bluebook's earlier name
+          # @return [String] `value`, stringified, as stored
+          def formerly_known_as(value)
+            bluebook_wide!(:formerly_known_as)
+            @formerly_known_as = value.to_s
+          end
+
+          # Names the Ruby module the bluebook's constants install under instead of its own name,
+          # such as `namespace "Hecks::Domain"` for a bluebook that would otherwise collide.
+          #
+          # @param value [String] a constant path, such as `"Hecks::Domain"`
+          # @return [String] `value`, stringified, as stored
+          def namespace(value)
+            bluebook_wide!(:namespace)
+            @namespace = value.to_s
+          end
+
+          # Classifies this bluebook as core to the framework, rather than a domain built on it.
+          #
+          # @return [Symbol] `:core`
+          def core       = classify(:core)
+
+          # Classifies this bluebook as a supporting piece of the framework, rather than a domain
+          # built on it.
+          #
+          # @return [Symbol] `:supporting`
+          def supporting = classify(:supporting)
+
+          # Classifies this bluebook as generic infrastructure, rather than a domain built on it.
+          #
+          # @return [Symbol] `:generic`
+          def generic    = classify(:generic)
+
+          private
+
+          # Sets how this bluebook is classified, which describes the whole of it.
+          def classify(kind)
+            bluebook_wide!(kind)
+            @classification = kind
+          end
+        end
+      end
+    end
+  end
+end