hecks 5.0.0 → 7.0.0

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/language/world/world.bluebook

@@ -24,16 +24,16 @@ Hecks.bluebook "World" do
       invariant("a latest version says something") { !value.to_s.empty? }
     end
 
-    # The connection every chapter's database-taking persistence adapter
-    # uses unless that chapter's own world says otherwise — a world's
-    # per-chapter `persisted_by ... database` block, written once.
+    # The connection every bluebook's database-taking persistence adapter
+    # uses unless that bluebook's own world says otherwise — a world's
+    # per-bluebook `persisted_by ... database` block, written once.
     value_object "DefaultDatabase" do
       attribute :value, String
       invariant("a default database says something") { !value.to_s.empty? }
     end
 
     # The persistence adapter every aggregate binds to unless its own
-    # chapter's hecksagon binds it — between an explicit bind and the
+    # bluebook's hecksagon binds it — between an explicit bind and the
     # framework's in-memory fallback.
     value_object "DefaultAdapter" do
       attribute :value, String
@@ -76,8 +76,8 @@ Hecks.bluebook "World" do
       member word: "world",           context: "File",     body: "keywords", inner: "World",          opens: "World",          fills: ""
       member word: "realm",           context: "World",     body: "none", inner: "", opens: "", fills: "realm", calls: "realm_impl"
       member word: "latest",          context: "World",     body: "none", inner: "", opens: "", fills: "latest", calls: "latest_impl"
-      # The connection string and persistence adapter every chapter of a
-      # project would otherwise repeat, written once here; a chapter's own
+      # The connection string and persistence adapter every bluebook of a
+      # project would otherwise repeat, written once here; a bluebook's own
       # world or hecksagon bind still wins.
       member word: "default_database", context: "World", body: "none", inner: "", opens: "", fills: "default_database", calls: "default_database_impl"
       member word: "default_adapter",  context: "World", body: "none", inner: "", opens: "", fills: "default_adapter", calls: "default_adapter_impl"

data/lib/hecks/literal.rb

@@ -81,11 +81,17 @@ module Hecks
 
     ESCAPED = { '"' => '\\"', "\\" => "\\\\" }.freeze
 
+    # A double quote or a backslash: the characters `quote` escapes.
+    NEEDS_ESCAPE = /["\\]/
+
+    # A backslash escape, capturing the character it escapes.
+    ESCAPE_SEQUENCE = /\\(.)/
+
     # Wraps `text` in double quotes, escaping embedded quotes and backslashes.
     #
     # @param text [String] raw text to quote
     # @return [String] the quoted, escaped spelling
-    def quote(text) = "\"#{text.gsub(/["\\]/) { |char| ESCAPED[char] }}\""
+    def quote(text) = "\"#{text.gsub(NEEDS_ESCAPE) { |char| ESCAPED[char] }}\""
 
     # Tells whether `raw` is a double-quoted literal.
     #
@@ -97,7 +103,7 @@ module Hecks
     #
     # @param raw [String] a quoted literal, as `quoted?` would confirm
     # @return [String] the unescaped text inside the quotes
-    def unquote(raw) = raw[1..-2].gsub(/\\(.)/) { ::Regexp.last_match(1) }
+    def unquote(raw) = raw[1..-2].gsub(ESCAPE_SEQUENCE) { ::Regexp.last_match(1) }
 
     # Parses a `{key: value, ...}` wire literal.
     #

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/naming.rb

@@ -6,6 +6,24 @@ module Hecks
     # join the same way, or string-compared references resolve to nothing.
     IDENTITY_JOIN = ":".freeze
 
+    # An uppercase run followed by a capitalised word: the "M|C" in "ATMCard".
+    ACRONYM_BOUNDARY = /([A-Z]+)([A-Z][a-z])/
+
+    # A lowercase letter or digit followed by an uppercase letter: the "y|L" in "dailyLimit".
+    CAMEL_BOUNDARY = /([a-z\d])([A-Z])/
+
+    # The first character of a word, captured.
+    FIRST_CHARACTER = /\A(.)/
+
+    # A word of two or more capitals and nothing else: an acronym such as "ATM".
+    ACRONYM = /\A[A-Z]{2,}\z/
+
+    # A consonant followed by a final "y", as in "category".
+    CONSONANT_Y_ENDING = /[^aeiou]y\z/
+
+    # A final s, x, z, ch or sh: the endings whose plural takes "es".
+    SIBILANT_ENDING = /(s|x|z|ch|sh)\z/
+
     module_function
 
     # Joins the parts of an identity in declaration order.
@@ -25,13 +43,20 @@ module Hecks
       type.to_s.split("::").last.to_s
     end
 
+    # The last segment of a dotted path: `"Pizzas.Pizza.Created"` -> `"Created"`.
+    #
+    # @param dotted [String, Symbol, #to_s] a `.`-joined path
+    # @return [String, nil] the text after the last `.`, the whole text if there is none, or nil
+    #   for an empty path
+    def last_segment(dotted) = dotted.to_s.split(".").last
+
     # snake_case -> PascalCase. Names a closed-set value object synthesised from an
     # inline attribute; the derivation is part of the IR contract.
     #
     # @param text [String, Symbol, #to_s] a snake_case (or already Pascal) name
     # @return [String] the PascalCase form
     def pascal(text)
-      text.to_s.split("_").map { |part| part.sub(/\A(.)/) { Regexp.last_match(1).upcase } }.join
+      text.to_s.split("_").map { |part| part.sub(FIRST_CHARACTER) { Regexp.last_match(1).upcase } }.join
     end
 
     # PascalCase or camelCase -> snake_case.
@@ -39,10 +64,19 @@ module Hecks
     # @param text [String, Symbol, #to_s] a Pascal-, camel-, or already snake-case name
     # @return [String] the lowercase, underscore-separated form
     def snake(text)
-      text.to_s
-          .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
-          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
-          .downcase
+      split_case(text, "_").downcase
+    end
+
+    # Puts `separator` at every case boundary of an identifier: before the capitalised word
+    # after an acronym, and between a lowercase letter or digit and the capital that follows.
+    #
+    # @param text [String, Symbol, #to_s] a Pascal- or camel-case name
+    # @param separator [String] what to put at each boundary, such as `"_"` or `" "`
+    # @return [String] the name with `separator` at each boundary, case unchanged
+    def split_case(text, separator)
+      replacement = "\\1#{separator}\\2"
+      acronyms_apart = text.to_s.gsub(ACRONYM_BOUNDARY, replacement)
+      acronyms_apart.gsub(CAMEL_BOUNDARY, replacement)
     end
 
     # An identifier as a sentence-cased phrase: `ATMCard` -> "ATM card",
@@ -51,13 +85,9 @@ module Hecks
     # @param text [String, Symbol, #to_s] a Pascal-, camel-, or snake-case identifier
     # @return [String] the space-separated, sentence-cased phrase
     def words(text)
-      parts = text.to_s
-                  .tr("_", " ")
-                  .gsub(/([A-Z]+)([A-Z][a-z])/, '\1 \2')
-                  .gsub(/([a-z\d])([A-Z])/, '\1 \2')
-                  .split
+      parts = split_case(text.to_s.tr("_", " "), " ").split
       parts.each_with_index.map do |part, index|
-        next part if part.match?(/\A[A-Z]{2,}\z/)
+        next part if part.match?(ACRONYM)
 
         index.zero? ? part.capitalize : part.downcase
       end.join(" ")
@@ -94,8 +124,8 @@ module Hecks
     # @return [String] the pluralised name
     def plural(text)
       word = text.to_s
-      return "#{word[0..-2]}ies" if word.match?(/[^aeiou]y\z/)
-      return "#{word}es"         if word.match?(/(s|x|z|ch|sh)\z/)
+      return "#{word[0..-2]}ies" if word.match?(CONSONANT_Y_ENDING)
+      return "#{word}es"         if word.match?(SIBILANT_ENDING)
 
       "#{word}s"
     end
@@ -122,7 +152,7 @@ module Hecks
     # @param word [String] a plural name
     # @return [Boolean] whether it is a sibilant stem plus `plural`'s "es"
     def sibilant_es?(word)
-      word.length > 3 && word.end_with?("es") && word[0..-3].match?(/(s|x|z|ch|sh)\z/)
+      word.length > 3 && word.end_with?("es") && word[0..-3].match?(SIBILANT_ENDING)
     end
 
     # Derives the attribute name a reference to `type` is stored under.

data/lib/hecks/persistence_legacy_fixture/postgres_stores.rb

@@ -35,9 +35,10 @@ module Hecks
         end
 
         def postgres_rows(instance)
-          adapter = Hecks::Adapters::Postgres.new(aggregate: instance.aggregate, settings: { database: SCRATCH[:postgres] })
+          aggregate = instance.aggregate
+          adapter = Hecks::Adapters::Postgres.new(aggregate: aggregate, settings: { database: SCRATCH[:postgres] })
           adapter.save(instance)
-          name = instance.aggregate.storage_name
+          name = aggregate.storage_name
           [name, stored_rows(adapter.instance_variable_get(:@db), name)]
         end
 
@@ -52,19 +53,19 @@ module Hecks
 
         def write_postgres_era(instances)
           reset_dir("postgres_era")
-          rows = instances.to_h { |instance| [instance.aggregate.storage_name, era_rows(instance)] }
+          rows = instances.to_h { |instance| [stored_as(instance.aggregate), era_rows(instance)] }
           write_json("postgres_era/rows.json", rows)
         end
 
         def era_rows(instance)
-          adapter = Hecks::Adapters::PostgresEra.new(aggregate: instance.aggregate,
-                                                     settings:  { database: SCRATCH[:postgres_era] })
+          aggregate = instance.aggregate
+          adapter = Hecks::Adapters::PostgresEra.new(aggregate: aggregate, settings: { database: SCRATCH[:postgres_era] })
           adapter.save(instance)
           db = adapter.instance_variable_get(:@db)
           snapshot = adapter.send(:quoted_head_snapshot)
           {
             "journal"       => journal_rows(db, adapter.instance_variable_get(:@lineage).quoted_journal,
-                                            instance.aggregate.storage_name),
+                                            aggregate.storage_name),
             "head_snapshot" => db.exec("SELECT id, ordinal, operation, state FROM #{snapshot} ORDER BY id").to_a
           }
         end

data/lib/hecks/persistence_legacy_fixture/regenerate.rb

@@ -76,7 +76,7 @@ module Hecks
           instances.each do |instance|
             Hecks::Adapters::Heki.new(aggregate: instance.aggregate, settings: { dir: "." }, root: tmp).save(instance)
             %w[heki heki.journal].each do |ext|
-              FileUtils.cp(File.join(tmp, "#{instance.aggregate.storage_name}.#{ext}"), out)
+              FileUtils.cp(File.join(tmp, "#{stored_as(instance.aggregate)}.#{ext}"), out)
             end
           end
         end
@@ -114,8 +114,12 @@ module Hecks
           Hecks::Adapters::D1.new(aggregate: instance.aggregate,
                                   settings:  { account_id: "acc", database_id: "db", api_token: "tok" }).save(instance)
         end
-        [instance.aggregate.storage_name, "#{instance.aggregate.storage_name}_entries"]
+        name = stored_as(instance.aggregate)
+        [name, "#{name}_entries"]
       end
+
+      # The table or file stem an aggregate's records are stored under.
+      def stored_as(aggregate) = aggregate.storage_name
     end
   end
 end

data/lib/hecks/ports/access_control.rb

@@ -26,8 +26,8 @@ module Hecks
 
       # Admits a new person, in whatever way this domain's adapter defines admission.
       #
-      # The keywords carry the names of a verified OIDC sign-in, but nothing here wires
-      # one to this port, so their shapes are adapter-defined.
+      # The keywords carry the names of a verified sign-in (`Ports::Authentication.verify`),
+      # but nothing here wires the two together, so their shapes are adapter-defined.
       #
       # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
       # @param email [Object] adapter-defined, forwarded unchanged; the person's email

data/lib/hecks/ports/agent/answers.rb

@@ -103,14 +103,14 @@ module Hecks
         # `Interview::Session#offer`'s call.
         #
         # @param row [Hash{String => Object}] one proposal row of the adapter's answer
-        # @return [String] the row's `"verb"`, shaped `Chapter::Aggregate.Command`
+        # @return [String] the row's `"verb"`, shaped `Bluebook::Aggregate.Command`
         # @raise [Ports::Agent::ValidationError] if the verb is missing or does not match
         #   `VERB_PATTERN`
         def verb!(row)
           verb = row["verb"].to_s
           return verb if VERB_PATTERN.match?(verb)
 
-          raise ValidationError, "#{verb.inspect} is not a fully-qualified verb (Chapter::Aggregate.Command)"
+          raise ValidationError, "#{verb.inspect} is not a fully-qualified verb (Bluebook::Aggregate.Command)"
         end
 
         # Reads a finding row's kind, refusing one outside the closed critique vocabulary.

data/lib/hecks/ports/agent.rb

@@ -63,7 +63,7 @@ module Hecks
       # @param state [Hash] declaration plus gaps
       # @return [Array<Ports::Agent::Proposal>]
       # @raise [Ports::Agent::ValidationError] unless the answer is a Hash whose `"proposals"`
-      #   rows have a `Chapter::Aggregate.Command` verb, a rationale and named arguments
+      #   rows have a `Bluebook::Aggregate.Command` verb, a rationale and named arguments
       # @raise [Ports::Agent::Unavailable] if the adapter cannot answer
       # @raise [Runtime::WiringError] unless exactly one adapter implements the port
       def interpret(registry, prose:, state:)
@@ -73,7 +73,7 @@ module Hecks
       # Asks the adapter to judge a declared model on taste.
       #
       # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
-      # @param declared [Hash] the chapter as declared so far
+      # @param declared [Hash] the bluebook as declared so far
       # @param refusals [Array<Object>] refusals the language already raised
       # @param findings [Array<Object>] `Session#gaps` findings; both are passed so the
       #   adapter spends its judgement on what neither can see

data/lib/hecks/ports/authentication.port

@@ -0,0 +1,6 @@
+Hecks.port "authentication" do
+  verb    "authenticated_by"
+  signal  :reply
+  answers :authorization_url
+  answers :verify
+end

data/lib/hecks/ports/authentication.rb

@@ -0,0 +1,67 @@
+require_relative "../runtime/registry"
+
+module Hecks
+  module Ports
+    # The OIDC handshake: builds the provider URL and turns the returned code into verified claims.
+    # One adapter registry-wide answers it; it never touches the registry's Identity data.
+    module Authentication
+      NAME = "authentication".freeze
+
+      # A sign-in that could not be verified (state mismatch, failed code exchange, bad ID token).
+      class ValidationError < StandardError
+      end
+
+      module_function
+
+      # Builds the provider URL that starts a sign-in, with the CSRF state minted for it.
+      #
+      # The caller keeps the state and hands it back to `verify` as `expected_state`.
+      #
+      # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
+      # @return [Array(String, String)] the URL to send the browser to, then the fresh
+      #   `state` value embedded in it
+      # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter
+      # @raise [KeyError] if the adapter's required configuration is unset
+      def authorization_url(registry)
+        adapter(registry).authorization_url
+      end
+
+      # Exchanges the authorization code a provider sent back for a Hash of verified claims.
+      #
+      # @param registry [Runtime::Registry] the booted registry to resolve the adapter against
+      # @param code [String] the authorization code the provider sent back
+      # @param state [String, nil] the state parameter the provider returned; nil is refused
+      # @param expected_state [String, nil] the state `authorization_url` returned; nil is refused
+      # @return [Hash{Symbol => Object}] the verified claims: `issuer:`, `subject:`, `email:`
+      #   (nil if the token carries none) and `email_verified:` -- never the raw token
+      # @raise [Ports::Authentication::ValidationError] if a state is nil or they differ, the
+      #   code exchange fails, or the ID token is missing or does not verify
+      # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter
+      # @raise [KeyError] if required configuration is unset, or the token lacks `iss`/`sub`
+      def verify(registry, code:, state:, expected_state:)
+        adapter(registry).verify(code: code, state: state, expected_state: expected_state)
+      end
+
+      # Finds the single adapter bound to this port.
+      #
+      # @raise [Runtime::WiringError] if none, or more than one, implements this port
+      def adapter(registry)
+        implementations = registry.adapters.values.select { |a| a.port == NAME }
+        return registry.adapter_class(implementations.first.name) if implementations.size == 1
+
+        raise Runtime::WiringError, wiring_refusal(implementations)
+      end
+
+      # Words the refusal for a port that resolves to no adapter or to several.
+      #
+      # @param implementations [Array] the adapters bound to this port
+      # @return [String] the error message
+      def wiring_refusal(implementations)
+        return "no adapter implements the #{NAME} port — nothing can authenticate a sign-in" if implementations.empty?
+
+        names = implementations.map(&:name).sort.join(", ")
+        "#{implementations.size} adapters implement the #{NAME} port (#{names}) — the runtime will not choose for you"
+      end
+    end
+  end
+end

data/lib/hecks/ports/authorization.rb

@@ -19,7 +19,7 @@ module Hecks
       # @param scope [String, nil] only a grant made for this scope counts; nil counts any scope
       # @return [Boolean] true if at least one live grant of `role` to `actor_id` passes
       # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter,
-      #   or the governance-backed adapter finds no single chapter providing `"authorization"`
+      #   or the governance-backed adapter finds no single bluebook providing `"authorization"`
       def holds_role?(registry, actor_id:, role:, as_of: nil, scope: nil)
         adapter(registry).holds_role?(registry, actor_id: actor_id, role: role, as_of: as_of, scope: scope)
       end
@@ -33,7 +33,7 @@ module Hecks
       # @return [Boolean] true if a live (not ended) allowance lets `from_role` act as
       #   `to_role`
       # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter,
-      #   or the governance-backed adapter finds no single loaded chapter providing
+      #   or the governance-backed adapter finds no single loaded bluebook providing
       #   `"authorization"`
       def authorized_as?(registry, from_role:, to_role:)
         adapter(registry).authorized_as?(registry, from_role: from_role, to_role: to_role)
@@ -46,7 +46,7 @@ module Hecks
       # @return [String, nil] the role name of the actor's first live (not ended) grant, or
       #   nil if it has none; the caller supplies any fallback
       # @raise [Runtime::WiringError] if this port does not resolve to exactly one adapter,
-      #   or the governance-backed adapter finds no single loaded chapter providing
+      #   or the governance-backed adapter finds no single loaded bluebook providing
       #   `"authorization"`
       def live_role_for(registry, actor_id:)
         adapter(registry).live_role_for(registry, actor_id: actor_id)

data/lib/hecks/ports/dispatch.port

@@ -0,0 +1,5 @@
+Hecks.port "dispatch" do
+  verb    "dispatched_by"
+  signal  :reply
+  answers :dispatcher
+end

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,26 +9,29 @@ 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.
-      def shred!(dispatcher, domain:, subject_id:) # rubocop:disable Naming/PredicateMethod
+      # 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:)
         provider = dispatcher.registry.provider_of(Bluebook::Capabilities::SUBJECT_KEYS)
         return false unless provider
 
         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