hecks 5.0.0 → 7.0.0

data/lib/hecks/framework/bluebook/privacy.bluebook

@@ -2,7 +2,7 @@ Hecks.bluebook "Privacy" do
   vision "Which fields of a domain's own aggregates are sensitive is a fact about that domain, declared apart from it — the domain itself never spells out that one of its own attributes is PII or PHI."
   supporting
 
-  # What this chapter answers for every attaching domain: the boot that seeds `mark_sensitive`
+  # What this bluebook answers for every attaching domain: the boot that seeds `mark_sensitive`
   # facts, the masking of a read and the cryptoshred read these verbs from here rather than
   # recognising "Privacy" by name.
   provides "privacy",
@@ -74,14 +74,15 @@ Hecks.bluebook "Privacy" do
     end
   end
 
-  # Cryptoshredding: erasure without rewriting events. `key_reference` is an opaque handle
-  # from `Ports::KeyVault.issue`, obtained before `Issue`; key material never appears here.
+  # Cryptoshredding: erasure without rewriting events. `key_reference` is an opaque handle the
+  # key vault answers an issue request with; key material never appears here.
   aggregate "SubjectKey" do
-    description "One data subject's own encryption key, from the moment it exists to the moment it is destroyed."
+    description "One data subject's own encryption key, from the moment it is asked for to the moment it is destroyed."
 
     attribute :domain,        KeyDomain
     attribute :subject_id,    SubjectId
-    attribute :key_reference, KeyReference
+    attribute :key_reference, KeyReference, optional: true
+    attribute :refusal,       Report, optional: true
 
     identified_by :domain, :subject_id
 
@@ -100,37 +101,101 @@ Hecks.bluebook "Privacy" do
       invariant("a key carries the vault's own opaque reference to it") { !value.to_s.empty? }
     end
 
-    # Guards `Shred` against running twice.
-    lifecycle :status, default: "active" do
-      transition "Shred" => "shredded", from: "active"
+    value_object "Report" do
+      attribute :value, String
+    end
+
+    # A key is asked for, then the vault issues it, then its reference is recorded (ADR 0147): the
+    # record reads `active` only once the vault named a key it holds. A refused issue leaves it
+    # `issue_failed`, which may be asked again. A shred is asked for, then the vault destroys the
+    # key, then it is recorded (ADR 0142): `shredded` only after the vault said the key is gone,
+    # and a refused destruction leaves `shred_failed`, which a privacy officer may ask again.
+    lifecycle :status, default: "issuing" do
+      mark :failure, "issue_failed", "shred_failed"
+      transition "RecordKey"    => "active",        from: "issuing"
+      transition "FailIssue"    => "issue_failed",  from: "issuing"
+      transition "Reissue"      => "issuing",       from: "issue_failed"
+      transition "Shred"        => "shredding",     from: ["active", "shred_failed"]
+      transition "MarkShredded" => "shredded",      from: "shredding"
+      transition "FailShred"    => "shred_failed",  from: "shredding"
+      mark :terminal, "shredded"
     end
 
+    # Asks for the key; it does not claim one. The `IssueTheKeyWhenAsked` policy asks the key vault,
+    # and `RecordKey` records the reference it answers with.
     command "Issue" do
       role "System"
-      goal "Record that a subject's data is now encrypted under a fresh, dedicated key"
+      goal "Ask for a fresh, dedicated key for a subject's data"
 
-      attribute :domain,        KeyDomain
-      attribute :subject_id,    SubjectId
-      attribute :key_reference, KeyReference
+      attribute :domain,     KeyDomain, sets: true
+      attribute :subject_id, SubjectId, sets: true
 
-      sets :domain
-      sets :subject_id
-      sets :key_reference
 
-      emits SubjectKeyIssued
+      emits SubjectKeyIssueRequested
     end
 
-    # Records the destruction, never performs it: `Ports::KeyVault.destroy` runs in
-    # driving-side code before this is dispatched.
+    # The vault named the key it holds. System-only, so no record claims a key by a caller's say-so.
+    command "RecordKey" do
+      role "System"
+      goal "Record the reference to the key the vault issued for this subject"
+
+      reference_to SubjectKey
+      attribute :key_reference, KeyReference, sets: true
+
+      emits SubjectKeyRecorded
+    end
+
+    command "FailIssue" do
+      role "System"
+      goal "Record why the vault could not issue this subject's key, leaving the request to repeat"
+
+      reference_to SubjectKey
+      attribute :refusal, Report, sets: true
+
+      emits SubjectKeyIssueFailed
+    end
+
+    command "Reissue" do
+      role "System"
+      goal "Ask again for a key the vault earlier refused to issue"
+
+      reference_to SubjectKey
+
+      emits SubjectKeyIssueRetried
+    end
+
+    # Asks for the destruction; it does not claim it. The `DestroyTheKeyWhenAsked` policy asks the
+    # key vault, and `MarkShredded` records the answer.
     command "Shred" do
       role "Privacy officer"
-      goal "Mark this subject's key destroyed, so its ciphertext is recorded as permanently unrecoverable"
+      goal "Ask for this subject's key to be destroyed, so its ciphertext becomes permanently unrecoverable"
 
       reference_to SubjectKey
 
+      emits SubjectKeyShredRequested
+    end
+
+    # The vault said the key is gone. System-only, so nothing reaches `shredded` by a caller's say-so.
+    command "MarkShredded" do
+      role "System"
+      goal "Record that the vault destroyed this subject's key, so its ciphertext is recorded as unrecoverable"
+
+      reference_to SubjectKey
+      attribute :key_reference, KeyReference
+
       emits SubjectKeyShredded
     end
 
+    command "FailShred" do
+      role "System"
+      goal "Record why the vault could not destroy this subject's key, leaving it live and the shred to retry"
+
+      reference_to SubjectKey
+      attribute :refusal, Report, sets: true
+
+      emits SubjectKeyShredFailed
+    end
+
     query "ForSubject" do
       description "One subject's key record, checked before any attempt to decrypt their sensitive fields."
       attribute :domain,     KeyDomain
@@ -138,4 +203,43 @@ Hecks.bluebook "Privacy" do
       where(domain: :domain, subject_id: :subject_id)
     end
   end
+
+  # What an issue does once asked for: the key vault issues the key, and its reference is recorded.
+  # The port is declared in privacy.ports.hecksagon and bound by privacy.key_keeper.adapter.
+  policy "IssueTheKeyWhenAsked" do
+    on  "SubjectKey.SubjectKeyIssueRequested"
+    ask :issue
+  end
+
+  policy "IssueTheKeyAgain" do
+    on  "SubjectKey.SubjectKeyIssueRetried"
+    ask :issue
+  end
+
+  policy "RecordTheKey" do
+    on      "SubjectKey.SubjectKeyIssued"
+    trigger SubjectKey::RecordKey, with: { key_reference: :key_reference }
+  end
+
+  policy "RecordTheIssueRefusal" do
+    on      "SubjectKey.SubjectKeyIssueRefused"
+    trigger SubjectKey::FailIssue, with: { refusal: :refusal }
+  end
+
+  # What a shred does once asked for: the key vault destroys the key, and the answer is recorded.
+  # The same port, bound by the same adapter.
+  policy "DestroyTheKeyWhenAsked" do
+    on  "SubjectKey.SubjectKeyShredRequested"
+    ask :destroy
+  end
+
+  policy "RecordTheDestruction" do
+    on      "SubjectKey.SubjectKeyDestroyed"
+    trigger SubjectKey::MarkShredded, with: { key_reference: :key_reference }
+  end
+
+  policy "RecordTheRefusal" do
+    on      "SubjectKey.SubjectKeyDestructionRefused"
+    trigger SubjectKey::FailShred, with: { refusal: :refusal }
+  end
 end

data/lib/hecks/framework/bluebook/privacy.key_keeper.adapter

@@ -0,0 +1,7 @@
+# Binds the `Keys` port to `KeyKeeper`, which has the key vault issue and destroy a subject's key.
+# Required by name, not relative, so a copy of this directory shares the one implementation loaded.
+require "hecks/adapters/driven/key_keeper"
+
+Hecks.adapter "KeyKeeper" do
+  port "Keys"
+end

data/lib/hecks/framework/bluebook/privacy.ports.hecksagon

@@ -0,0 +1,19 @@
+# The port Privacy declares, for every hecksagon that attaches the bluebook (`Framework.load!` loads
+# this file with it). `Issue` asks the key vault for a key for a subject and answers with the
+# reference to it; `Destroy` asks it to destroy a subject's key and answers once it is gone. Each
+# refuses with a reason. privacy.key_keeper.adapter binds both (ADR 0142, ADR 0147).
+Hecks.hecksagon "Privacy" do
+  Privacy::SubjectKey.port "Keys" do
+    # No argument: the ask is handed the subject's held state, which names the subject.
+    asks "Issue", to: SubjectKey do
+      answers "SubjectKeyIssued"
+      refuses "SubjectKeyIssueRefused"
+    end
+
+    # No argument: the ask is handed the subject's held state, which names the key.
+    asks "Destroy", to: SubjectKey do
+      answers "SubjectKeyDestroyed"
+      refuses "SubjectKeyDestructionRefused"
+    end
+  end
+end

data/lib/hecks/framework/compliance.oidc.json

@@ -2,48 +2,18 @@
   "audience": "Compliance",
   "scopes": [
     {
-      "scope": "compliance:account_freeze_review.clear",
-      "verb": "Compliance::AccountFreezeReview.Clear",
+      "scope": "compliance:review.clear",
+      "verb": "Compliance::Review.Clear",
       "role": "Compliance officer"
     },
     {
-      "scope": "compliance:account_freeze_review.escalate",
-      "verb": "Compliance::AccountFreezeReview.Escalate",
+      "scope": "compliance:review.escalate",
+      "verb": "Compliance::Review.Escalate",
       "role": "Compliance officer"
     },
     {
-      "scope": "compliance:account_freeze_review.open",
-      "verb": "Compliance::AccountFreezeReview.Open",
-      "role": "System"
-    },
-    {
-      "scope": "compliance:box_surrender_review.clear",
-      "verb": "Compliance::BoxSurrenderReview.Clear",
-      "role": "Compliance officer"
-    },
-    {
-      "scope": "compliance:box_surrender_review.escalate",
-      "verb": "Compliance::BoxSurrenderReview.Escalate",
-      "role": "Compliance officer"
-    },
-    {
-      "scope": "compliance:box_surrender_review.open",
-      "verb": "Compliance::BoxSurrenderReview.Open",
-      "role": "System"
-    },
-    {
-      "scope": "compliance:privacy_review.clear",
-      "verb": "Compliance::PrivacyReview.Clear",
-      "role": "Compliance officer"
-    },
-    {
-      "scope": "compliance:privacy_review.escalate",
-      "verb": "Compliance::PrivacyReview.Escalate",
-      "role": "Compliance officer"
-    },
-    {
-      "scope": "compliance:privacy_review.open",
-      "verb": "Compliance::PrivacyReview.Open",
+      "scope": "compliance:review.open",
+      "verb": "Compliance::Review.Open",
       "role": "System"
     }
   ],

data/lib/hecks/framework/console_settings.oidc.json

@@ -7,63 +7,78 @@
       "role": "Console"
     },
     {
-      "scope": "console_settings:collection.replace_columns",
-      "verb": "ConsoleSettings::Collection.ReplaceColumns",
+      "scope": "console_settings:collection.set_extra",
+      "verb": "ConsoleSettings::Collection.SetExtra",
       "role": "Console"
     },
     {
-      "scope": "console_settings:collection.replace_detail_field_columns",
-      "verb": "ConsoleSettings::Collection.ReplaceDetailFieldColumns",
+      "scope": "console_settings:collection.set_key",
+      "verb": "ConsoleSettings::Collection.SetKey",
       "role": "Console"
     },
     {
-      "scope": "console_settings:collection.replace_detail_fields",
-      "verb": "ConsoleSettings::Collection.ReplaceDetailFields",
+      "scope": "console_settings:collection.set_label",
+      "verb": "ConsoleSettings::Collection.SetLabel",
       "role": "Console"
     },
     {
-      "scope": "console_settings:collection.replace_field_formats",
-      "verb": "ConsoleSettings::Collection.ReplaceFieldFormats",
+      "scope": "console_settings:collection.set_list_query",
+      "verb": "ConsoleSettings::Collection.SetListQuery",
       "role": "Console"
     },
     {
-      "scope": "console_settings:collection.replace_preconditions",
-      "verb": "ConsoleSettings::Collection.ReplacePreconditions",
+      "scope": "console_settings:collection.set_nav_order",
+      "verb": "ConsoleSettings::Collection.SetNavOrder",
       "role": "Console"
     },
     {
-      "scope": "console_settings:collection.set_extra",
-      "verb": "ConsoleSettings::Collection.SetExtra",
+      "scope": "console_settings:collection.set_primary_field",
+      "verb": "ConsoleSettings::Collection.SetPrimaryField",
       "role": "Console"
     },
     {
-      "scope": "console_settings:collection.set_identity",
-      "verb": "ConsoleSettings::Collection.SetIdentity",
+      "scope": "console_settings:collection_identity.declare",
+      "verb": "ConsoleSettings::CollectionIdentity.Declare",
       "role": "Console"
     },
     {
-      "scope": "console_settings:collection.set_key",
-      "verb": "ConsoleSettings::Collection.SetKey",
+      "scope": "console_settings:collection_identity.set_identity",
+      "verb": "ConsoleSettings::CollectionIdentity.SetIdentity",
       "role": "Console"
     },
     {
-      "scope": "console_settings:collection.set_label",
-      "verb": "ConsoleSettings::Collection.SetLabel",
+      "scope": "console_settings:collection_layout.declare",
+      "verb": "ConsoleSettings::CollectionLayout.Declare",
       "role": "Console"
     },
     {
-      "scope": "console_settings:collection.set_list_query",
-      "verb": "ConsoleSettings::Collection.SetListQuery",
+      "scope": "console_settings:collection_layout.replace_columns",
+      "verb": "ConsoleSettings::CollectionLayout.ReplaceColumns",
       "role": "Console"
     },
     {
-      "scope": "console_settings:collection.set_nav_order",
-      "verb": "ConsoleSettings::Collection.SetNavOrder",
+      "scope": "console_settings:collection_layout.replace_detail_field_columns",
+      "verb": "ConsoleSettings::CollectionLayout.ReplaceDetailFieldColumns",
       "role": "Console"
     },
     {
-      "scope": "console_settings:collection.set_primary_field",
-      "verb": "ConsoleSettings::Collection.SetPrimaryField",
+      "scope": "console_settings:collection_layout.replace_detail_fields",
+      "verb": "ConsoleSettings::CollectionLayout.ReplaceDetailFields",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection_rules.declare",
+      "verb": "ConsoleSettings::CollectionRules.Declare",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection_rules.replace_field_formats",
+      "verb": "ConsoleSettings::CollectionRules.ReplaceFieldFormats",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection_rules.replace_preconditions",
+      "verb": "ConsoleSettings::CollectionRules.ReplacePreconditions",
       "role": "Console"
     },
     {

data/lib/hecks/framework/privacy.oidc.json

@@ -11,11 +11,36 @@
       "verb": "Privacy::Marking.Unmark",
       "role": "Deployment"
     },
+    {
+      "scope": "privacy:subject_key.fail_issue",
+      "verb": "Privacy::SubjectKey.FailIssue",
+      "role": "System"
+    },
+    {
+      "scope": "privacy:subject_key.fail_shred",
+      "verb": "Privacy::SubjectKey.FailShred",
+      "role": "System"
+    },
     {
       "scope": "privacy:subject_key.issue",
       "verb": "Privacy::SubjectKey.Issue",
       "role": "System"
     },
+    {
+      "scope": "privacy:subject_key.mark_shredded",
+      "verb": "Privacy::SubjectKey.MarkShredded",
+      "role": "System"
+    },
+    {
+      "scope": "privacy:subject_key.record_key",
+      "verb": "Privacy::SubjectKey.RecordKey",
+      "role": "System"
+    },
+    {
+      "scope": "privacy:subject_key.reissue",
+      "verb": "Privacy::SubjectKey.Reissue",
+      "role": "System"
+    },
     {
       "scope": "privacy:subject_key.shred",
       "verb": "Privacy::SubjectKey.Shred",

data/lib/hecks/framework.rb

@@ -1,4 +1,5 @@
 require_relative "runtime/registry"
+require_relative "sentence_form"
 
 module Hecks
   # Registry of framework bluebooks (Governance, Identity, ...) in `lib/hecks/framework/bluebook/`.
@@ -25,15 +26,15 @@ module Hecks
     # @return [Array<String>] the names of every framework member that provides it,
     #   sorted
     def self.providers_of(capability)
-      members.keys.select { |name| chapter(name).provides?(capability) }.sort
+      members.keys.select { |name| declaration(name).provides?(capability) }.sort
     end
 
-    # One member's chapter, built in isolation.
+    # One member's bluebook, built in isolation.
     #
     # @param name [String, Symbol] the member's name, such as `"Governance"`
-    # @return [Bluebook::Chapter] the member's chapter, loaded into a scratch registry
+    # @return [Bluebook::Declaration] the member's bluebook, loaded into a scratch registry
     # @raise [Runtime::WiringError] if no framework member has that name
-    def self.chapter(name)
+    def self.declaration(name)
       path = members.fetch(name.to_s) do
         raise Runtime::WiringError,
               "no framework member named #{name.inspect} — known: #{members.keys.sort.join(", ")}"
@@ -43,17 +44,17 @@ module Hecks
     end
 
     # @param path [String] a member's bluebook file
-    # @return [Runtime::Registry] a fresh registry holding only that member's chapter
+    # @return [Runtime::Registry] a fresh registry holding only that member's bluebook
     def self.scratch_registry(path)
       lib = File.expand_path("..", __dir__)
       registry = Runtime::Registry.new
       Hecks.with_registry(registry) do
-        # A chapter needs these four to build (predicate source is recovered via extraction).
+        # A bluebook needs these four to build (predicate source is recovered via extraction).
         Kernel.load(File.join(lib, "hecks/ports/persistence.port"))
         Kernel.load(File.join(lib, "hecks/ports/extraction.port"))
         Kernel.load(File.join(lib, "hecks/adapters/driven/memory.adapter"))
         Kernel.load(File.join(lib, "hecks/adapters/driven/prism.adapter"))
-        Kernel.load(path)
+        SentenceForm.load_file(path)
       end
       registry
     end
@@ -76,7 +77,22 @@ module Hecks
 
       return if Hecks.current_registry.bluebook(name.to_s)
 
-      Kernel.load(path)
+      SentenceForm.load_file(path)
+      load_wiring(path)
     end
+
+    # Loads what a member ships beside its bluebook, as {Bluebooks} does for the bluebooks it
+    # carries: `<name>.ports.hecksagon` (the ports it declares) and `<name>.*.adapter` (the
+    # adapters binding them). A member with neither loads exactly the bluebook, as before.
+    #
+    # @param path [String] the member's bluebook file
+    # @return [void]
+    def self.load_wiring(path)
+      stem = File.join(File.dirname(path), File.basename(path, ".bluebook"))
+      ports = "#{stem}.ports.hecksagon"
+      Kernel.load(ports) if File.file?(ports)
+      Dir.glob("#{stem}.*.adapter").each { |adapter| Kernel.load(adapter) }
+    end
+    private_class_method :load_wiring
   end
 end

data/lib/hecks/framework_bluebooks.rb

@@ -0,0 +1,181 @@
+require_relative "naming"
+require_relative "framework"
+require_relative "runtime/registry"
+require_relative "bluebook/meta_validator"
+require_relative "sentence_form"
+
+module Hecks
+  # The bluebooks the gem carries that a hecksagon can attach by name (ADR 0080): the language
+  # declared in itself, Expression, Tenancy, Deploy, Site, Tickets, Composer, QualityControl,
+  # Fixer, Coder, Bulk and CiPipeline.
+  # Framework members stay in `Framework`; `table` and `attach!` find a name across both.
+  #
+  # A bluebook is named by the `Hecks.bluebook "Name"` header of its files, and may span several.
+  # Beside its bluebook a bluebook may carry what every hecksagon attaching it needs, whatever
+  # its store: `<snake_name>.ports.hecksagon` (the ports it declares, as a `Hecks.hecksagon`
+  # block that merges into the attaching one) and `adapters/*.adapter` (the adapters binding them).
+  module FrameworkBluebooks
+    # Where attachable bluebooks live, relative to `lib/hecks/`.
+    GLOBS = %w[language/**/*.bluebook grammar/expression.bluebook tenancy/bluebook/*.bluebook
+               deploy/bluebook/*.bluebook site/bluebook/*.bluebook rails_app/bluebook/*.bluebook tickets/bluebook/*.bluebook
+               composer/bluebook/*.bluebook quality_control/*.bluebook fixer/*.bluebook coder/*.bluebook
+               bulk/bluebook/*.bluebook ci_pipeline/*.bluebook].freeze
+
+    # A `Hecks.bluebook "Name"` header line, capturing the bluebook's name.
+    BLUEBOOK_HEADER = /\A\s*Hecks\.bluebook\s+"([^"]+)"/
+
+    # Every attachable bluebook, by name, with the files that declare it.
+    #
+    # @return [Hash{String => Array<String>}] bluebook name to its files' absolute paths, sorted
+    def self.index
+      @index ||= bluebook_files.group_by { |path| declaration_name(path) }
+                               .reject { |name, _| name.nil? }
+                               .freeze
+    end
+
+    # @return [Array<String>] every file the globs find, sorted
+    def self.bluebook_files
+      GLOBS.flat_map { |glob| Dir.glob(File.join(__dir__, glob)) }.sort
+    end
+
+    # Every bluebook the gem carries, whichever module loads it: the one lookup table `attaches`
+    # finds a name in.
+    #
+    # @return [Hash{String => Array<String>}] bluebook name to its files' absolute paths, the
+    #   framework members (`Framework.members`) and the attachable bluebooks (`index`) together
+    def self.table
+      Framework.members.transform_values { |path| [path] }.merge(index)
+    end
+
+    # Loads one gem bluebook by name, found in `table`: a framework member through
+    # `Framework.load!`, any other bluebook through `load!`.
+    #
+    # @param name [String, Symbol] the bluebook's name, such as `"Governance"` or `"Deploy"`
+    # @return [Boolean, nil] true when this call loaded it, nil when it was already held
+    # @raise [Runtime::WiringError] if the gem carries no bluebook of that name; the message
+    #   lists the known names and says how to attach a vendored package
+    def self.attach!(name)
+      key = name.to_s
+      return Framework.load!(key) if Framework.members.key?(key)
+      return load!(key) if index.key?(key)
+
+      raise Runtime::WiringError,
+            "attaches #{name.inspect}: the gem carries no bluebook of that name — known: " \
+            "#{table.keys.sort.join(", ")}. To attach a vendored package, write " \
+            "`attaches #{name.to_s.inspect}, from: :vendor`"
+    end
+
+    # Loads a bluebook's files into the current registry, unless it already holds the bluebook.
+    #
+    # The files load together inside `MetaValidator.defer`, so a bluebook spread over several files
+    # is judged once, whole. The bluebook's ports file and adapters load after it, since a port
+    # names the bluebook's aggregates.
+    #
+    # @param name [String] the bluebook's name, such as `"Deploy"`
+    # @return [Boolean, nil] true when this call loaded the bluebook, nil when it was already held
+    # @raise [Runtime::WiringError] if no attachable bluebook has that name
+    def self.load!(name)
+      paths = bluebook_paths(name)
+      registry = open_registry(name)
+      return refuse_own_bluebook(registry, name.to_s) if registry.bluebook(name.to_s)
+
+      load_atomically(registry, name.to_s, paths)
+      true
+    end
+
+    # @return [Array<String>] the files of the named bluebook
+    # @raise [Runtime::WiringError] if no attachable bluebook has that name
+    def self.bluebook_paths(name)
+      index.fetch(name.to_s) do
+        raise Runtime::WiringError,
+              "no attachable bluebook named #{name.inspect} — known: #{index.keys.join(", ")}"
+      end
+    end
+
+    # @return [Runtime::Registry] the registry the current boot is loading into
+    # @raise [Runtime::WiringError] when no boot is open
+    def self.open_registry(name)
+      Hecks.current_registry or
+        raise Runtime::WiringError, "attaches #{name.to_s.inspect} outside a boot: no registry is open"
+    end
+
+    # Loads a bluebook whole or not at all: a raise anywhere leaves the registry as it was, so a
+    # retry loads the bluebook again instead of finding a half-built one already held.
+    def self.load_atomically(registry, name, paths)
+      before = { queued: Bluebook::MetaValidator.deferred_bluebooks.dup, ports: registry.ports.keys,
+                 adapters: registry.adapters.keys }
+      Bluebook::MetaValidator.defer { paths.each { |path| SentenceForm.load_file(path) } }
+      Bluebook::MetaValidator.judge_deferred!(registry)
+      load_wiring(name, paths)
+    rescue Exception
+      roll_back(registry, name, before)
+      raise
+    end
+
+    # Puts the registry back as `load_atomically` found it.
+    def self.roll_back(registry, name, before)
+      registry.forget_bluebook(name)
+      Bluebook::MetaValidator.deferred_bluebooks.replace(before[:queued])
+      registry.ports.delete_if { |key, _| !before[:ports].include?(key) }
+      registry.adapters.delete_if { |key, _| !before[:adapters].include?(key) }
+    end
+    private_class_method :bluebook_files, :bluebook_paths, :open_registry, :load_atomically, :roll_back
+
+    # Returns nil for a bluebook this gem already loaded; raises for a bluebook of the same name
+    # that a user's own file declared, which `attaches` would otherwise silently take for the
+    # gem's.
+    def self.refuse_own_bluebook(registry, name)
+      foreign = Array(registry.bluebook_sources[name]).compact
+                                                      .reject { |path| File.expand_path(path).start_with?("#{__dir__}/") }
+      return if foreign.empty?
+
+      raise Runtime::WiringError,
+            "attaches #{name.inspect}, but a bluebook named #{name.inspect} is already declared in " \
+            "#{foreign.join(", ")} — rename it, since the gem's own #{name} bluebook cannot merge into it"
+    end
+    private_class_method :refuse_own_bluebook
+
+    # Loads what a bluebook ships beside its bluebook: its ports file, then its adapters.
+    #
+    # @param name [String] the bluebook's name
+    # @param paths [Array<String>] the bluebook's bluebook files
+    # @return [void]
+    def self.load_wiring(name, paths)
+      wiring_files(name, paths).each { |file| Kernel.load(file) }
+    end
+    private_class_method :load_wiring
+
+    # The files `load_wiring` loads, in the order it loads them: the ports file, then the adapters.
+    #
+    # @param name [String] the bluebook's name
+    # @param paths [Array<String>] the bluebook's bluebook files
+    # @return [Array<String>] the ports file when there is one, then each adapter file
+    def self.wiring_files(name, paths)
+      directory = File.dirname(paths.first)
+      ports     = File.join(directory, "#{Naming.snake(name)}.ports.hecksagon")
+      [*(ports if File.file?(ports)), *Dir.glob(File.join(directory, "adapters", "*.adapter"))]
+    end
+    private_class_method :wiring_files
+
+    # Every file attaching the named bluebook reads: a framework member's one file, or an
+    # attachable bluebook's files with the ports file and adapters it ships. What a cache of a
+    # generated tree hashes to know when attaching the bluebook would write something else.
+    #
+    # @param name [String, Symbol] the bluebook's name, such as `"Governance"`
+    # @return [Array<String>] the files' absolute paths
+    # @raise [Runtime::WiringError] if the gem carries no bluebook of that name
+    def self.files_of(name)
+      key = name.to_s
+      return [Framework.members.fetch(key)] if Framework.members.key?(key)
+
+      paths = bluebook_paths(key)
+      [*paths, *wiring_files(key, paths)]
+    end
+
+    # The name a file's `Hecks.bluebook "Name"` header declares, or nil for a file without one.
+    def self.declaration_name(path)
+      File.foreach(path) { |line| return Regexp.last_match(1) if line =~ BLUEBOOK_HEADER }
+      nil
+    end
+  end
+end