hecks 4.0.0 → 6.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: acccf4e21574d64b971cfbfe6a34f08f0bc86fdb8c74a8c58a472042138f01f1
-  data.tar.gz: 582d4e043a4b0145c25f6dfa8e223c47da7f55e60205fbef6485f6b406a2ffe2
+  metadata.gz: 07b3cc0e62a206f392a32139dd069289f720c19e3b00b9fd09ed47bfa6a814bc
+  data.tar.gz: 5102854abcb5b29ee39b8b45323b5a48b874ea7f149509025a8bc801b51fb337
 SHA512:
-  metadata.gz: 01f4db2b60db4d05aa7682fb7abdab6206abae36f45031656b9461fa064ec61236301b731f0b64c58cdee4d26624fe8a9d61042c379ae34f3274d036b31644ad
-  data.tar.gz: 9d1c2b9990aa214173c76634eda0dbe2f32651e80fe27e54c204d1cf0877a25e00334fc2784700754cf502196548b8e3a59549974f68789e5e31dd8defb5c0be
+  metadata.gz: 7c8841943da9eab5cbbc6be160b76a54d333537fee1ed983d7f9c4dace82029b9f6f8f3d9a57389baedc35866ac76ffa74e3b81037c575396b5fe480a4eb1c60
+  data.tar.gz: c9bf331909c4cf19c429986fb75a53c40d98feb01c198b4bcfd613c132fe03badd5dc8e15a67024fea124a5646ddaa2da5737f4d5b855478fcbcbb50dba44c96

data/examples/pizzas/bluebook/pizzas.bluebook

@@ -64,6 +64,7 @@ Hecks.bluebook "Pizzas" do
 
     lifecycle :status, default: "available" do
       transition "Purchase" => "sold", from: "available"
+      mark :terminal, "sold"
     end
 
     query "Available" do

data/exe/hecks

@@ -4,7 +4,7 @@
 #
 # A launcher, not a CLI: the commands, their arguments and their refusals are
 # projected from the bluebook beside it every time this runs, so a change
-# to the chapter shows up here without re-minting anything.
+# to the bluebook shows up here without re-minting anything.
 #
 #   exe/hecks                  every command, and every question
 #   exe/hecks <command> --help    what it wants, and how it refuses
@@ -14,6 +14,18 @@ Encoding.default_internal = Encoding::UTF_8
 
 $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 
+# In a hecks checkout this runs on the gems the Gemfile pins, as `bundle exec` and CI do.
+# Beside an installed gem, or where that set is not installed, it runs on the gems at hand.
+gemfile = File.expand_path("../Gemfile", __dir__)
+if File.exist?(File.expand_path("../hecks.gemspec", __dir__)) && File.exist?(gemfile)
+  ENV["BUNDLE_GEMFILE"] ||= gemfile
+  begin
+    require "bundler/setup"
+  rescue LoadError, StandardError
+    nil
+  end
+end
+
 # The names the gem has always shipped keep their positional forms.
 LEGACY = %w[run docs narrate ir stores model_check smoke_test project_diagrams project_cli mcp].freeze
 if LEGACY.include?(ARGV.first)
@@ -30,7 +42,7 @@ ARGV << "--wait" if MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!")) && !ARG
 
 require "hecks"
 
-# Usage is answered from the projected chapter alone: no adapter is bound and no
+# Usage is answered from the projected bluebook alone: no adapter is bound and no
 # database is opened. Only a line that runs a command boots the domain,
 # and it boots from what the usage check already loaded.
 domain = File.expand_path("../lib/hecks/hecks", __dir__)
@@ -63,7 +75,7 @@ if reason
   if MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!"))
     why = begin
       require "json"
-      JSON.parse(text).dig("state", "refusal", "value")
+      JSON.parse(text).dig("state", "refusal")
     rescue JSON::ParserError
       nil
     end

data/lib/hecks/adapters/driven/claude_code.rb

@@ -30,7 +30,7 @@ module Hecks
         call(
           system:  SYSTEM_PREFIX + "Given the domain model so far and a sentence the human just said, " \
                                    "propose zero or more declarations that capture what the sentence names as domain " \
-                                   "fact. A verb must be fully qualified as Chapter::Aggregate.Command. Reply as " \
+                                   "fact. A verb must be fully qualified as Bluebook::Aggregate.Command. Reply as " \
                                    '{"proposals": [{"verb": "...", "rationale": "...", "arguments": ' \
                                    '[{"name": "...", "field": "...", "value": "..."}]}]}. If the sentence carries no ' \
                                    'declaration (a question back, a clarification), reply {"proposals": []}.',

data/lib/hecks/adapters/driven/d1.rb

@@ -93,7 +93,8 @@ module Hecks
         results = @db.batch([status_statement(entry, insert_only),
                              entry_statement(entry, insert_only),
                              aggregate_statement(entry, insert_only)])
-        results.fetch(0).fetch(0).fetch("status").to_sym
+        status_row = results.fetch(0).fetch(0)
+        status_row.fetch("status").to_sym
       end
 
       private

data/lib/hecks/adapters/driven/folder.rb

@@ -1,10 +1,15 @@
 require_relative "../../vocabulary"
+require_relative "../../ports/loading"
+require_relative "../../sentence_form"
+require_relative "folder_overlay"
 
 module Hecks
   module Adapters
     # Loads a domain's files off disk in `Vocabulary.fetch("LoadOrder")` order and finds
     # a domain's root directory. Used by `Hecks.boot(path)` when given a directory.
     class Folder
+      include FolderOverlay
+
       DOMAIN_ORDER = Hecks::Vocabulary.fetch("LoadOrder")
       PORTS        = "ports".freeze
       ADAPTERS     = "adapters".freeze
@@ -28,20 +33,22 @@ module Hecks
       #
       # @param root [String, nil] the shared root directory, as `shared_root` resolves it;
       #   nil is a no-op
+      # @param adapters [Boolean] false leaves the root's adapters unloaded, for a boot that names
+      #   its own (see `load_selected`)
       # @return [void]
-      def load_project(root)
+      def load_project(root, adapters: true)
         return unless root
 
-        load_each(File.join(root, PORTS),    %w[*.port */*.port])
-        load_each(File.join(root, ADAPTERS), %w[*.adapter */*.adapter */*/*.adapter])
+        load_each(File.join(root, PORTS), %w[*.port */*.port])
+        load_each(File.join(root, ADAPTERS), %w[*.adapter */*.adapter */*/*.adapter]) if adapters
       end
 
-      # Loads bluebook chapters first, judged once as a deferred group, then everything
-      # else in `DOMAIN_ORDER`. Deferring keeps a chapter split across files from being
+      # Loads bluebooks first, judged once as a deferred group, then everything
+      # else in `DOMAIN_ORDER`. Deferring keeps a bluebook split across files from being
       # judged before its later files exist (see MetaValidator.defer).
       #
-      # An `environment:` overlay (`environments/<name>.hecksagon` and `.world`) loads
-      # last and merges into the base hecksagon/world; a missing overlay file is skipped.
+      # Then the overlays merge into the base hecksagon/world: the copy's own, then the named
+      # `environment:` one (see `load_overlay`); a missing overlay file is skipped.
       #
       # @param directory [String] the domain's bluebook directory to load, as
       #   `bluebook_directory` resolves it
@@ -60,24 +67,12 @@ module Hecks
         load_overlay(directory, environment)
       end
 
-      # Loads an environment's `.hecksagon` then `.world` overlay files, when present.
-      #
-      # @param directory [String] the directory holding the `environments/` folder
-      # @param environment [String, nil] the environment name; nil loads nothing
-      # @return [void]
-      def load_overlay(directory, environment)
-        return unless environment
-
-        load_each(directory, [File.join("environments", "#{environment}.hecksagon")])
-        load_each(directory, [File.join("environments", "#{environment}.world")])
-      end
-
       # Loads every bluebook in a folder as one declaration set, judged after all are loaded
-      # so cross-file references never meet a partial chapter.
+      # so cross-file references never meet a partial bluebook.
       #
-      # @param directory [String] the directory to glob for bluebook chapter files
+      # @param directory [String] the directory to glob for bluebook files
       # @param patterns [Array<String>] glob patterns, relative to `directory`, selecting the
-      #   chapter files to load
+      #   bluebook files to load
       # @return [void]
       def load_bluebooks(directory, patterns = ["*.bluebook"])
         Bluebook::MetaValidator.defer { load_each(directory, patterns) }
@@ -87,7 +82,9 @@ module Hecks
       # Loads exactly the named files in place, without globbing (see `Loader.boot_files`).
       #
       # Files load by category, not in the caller's order: bluebooks (judged as one deferred
-      # group), then hecksagons, then worlds, since a hecksagon may reference bluebook constants.
+      # group), then hecksagons, worlds and context maps, since a hecksagon may reference bluebook
+      # constants, then any adapters named, which stand in for the shared root's (see
+      # `Loader.load_files`).
       #
       # @param files [Array<String>] file paths to load, relative to `bluebook_directory`
       # @param environment [String, nil] the environment name whose overlay, if present,
@@ -96,7 +93,7 @@ module Hecks
       def load_selected(files, environment: nil)
         bluebooks, rest = files.partition { |f| f.end_with?(".bluebook") }
         load_selected_bluebooks(bluebooks)
-        %w[.hecksagon .world].each do |ext|
+        %w[.hecksagon .world .contextmap .adapter].each do |ext|
           rest.select { |f| f.end_with?(ext) }.sort.each { |f| Kernel.load(f) }
         end
         load_overlay(File.dirname(files.first), environment) if environment
@@ -109,10 +106,18 @@ module Hecks
       def load_selected_bluebooks(bluebooks)
         return if bluebooks.empty?
 
-        Bluebook::MetaValidator.defer { bluebooks.sort.each { |f| Kernel.load(f) } }
+        Bluebook::MetaValidator.defer { bluebooks.sort.each { |f| load_file(f) } }
         Bluebook::MetaValidator.judge_deferred!(Hecks.current_registry)
       end
 
+      # Loads one file in whichever form it is written (see {SentenceForm.load_file}).
+      #
+      # @param file [String] the file to load
+      # @return [void]
+      def load_file(file)
+        SentenceForm.load_file(file)
+      end
+
       # Loads every file under `directory` matching any of `patterns`, in pattern order.
       #
       # A no-op if `directory` does not exist.
@@ -125,14 +130,14 @@ module Hecks
         return unless File.directory?(directory)
 
         patterns.each do |pattern|
-          Dir[File.join(directory, pattern)].each { |file| Kernel.load(file) }
+          Dir[File.join(directory, pattern)].reject { |file| left_to_overlay?(file, pattern) }.each { |file| load_file(file) }
         end
       end
 
       # Resolves a domain path to the directory that actually holds its bluebook files.
       #
       # @param path [String] a domain directory, holding either a `bluebook/` subdirectory or
-      #   its chapter files directly
+      #   its bluebook files directly
       # @return [String] the `bluebook/` subdirectory's absolute path, if one exists; `path`'s
       #   own absolute path otherwise
       # @raise [Errno::ENOENT] if neither directory exists
@@ -149,7 +154,7 @@ module Hecks
       # Finds the nearest domain directory at or above `from`, or nil if there is not one.
       #
       # Walks up from `from`, like git finding `.git`. A domain is marked by a `.hecksagon`,
-      # not a `.bluebook`, since chapters also appear in translations and fixtures.
+      # not a `.bluebook`, since bluebooks also appear in translations and fixtures.
       #
       # A `bluebook/` subdirectory result is normalised to its parent, the directory
       # a `.world`'s `dir "data"` is relative to.
@@ -228,3 +233,5 @@ module Hecks
     end
   end
 end
+
+Hecks::Ports::Loading.bootstrap_with(Hecks::Adapters::Folder)

data/lib/hecks/adapters/driven/folder_overlay.rb

@@ -0,0 +1,51 @@
+module Hecks
+  module Adapters
+    # The files a copy of a domain keeps for itself, loaded after the domain's own: its overlay,
+    # its bluebooks' local worlds, and a named environment's overlay. `Folder` mixes this in.
+    module FolderOverlay
+      # The overlay one copy of a domain keeps for itself, such as the database its own runs
+      # record to. `.gitignore` keeps it out of the repository, so no other copy ever reads it.
+      LOCAL_OVERLAY = "local".freeze
+
+      # A bluebook's local files, `<bluebook>.local.hecksagon` and `<bluebook>.local.world`: where a
+      # copy, or a client's working directory, opts a bluebook into persistence, the hecksagon with
+      # `persisted_by` and the world with the values. The base names no persistence, so Memory is
+      # the default.
+      LOCAL_FILES = %w[*.local.hecksagon *.local.world].freeze
+
+      # The name of a file that is local: a `.local.hecksagon` or a `.local.world`.
+      LOCAL_FILE_NAME = /\.local\.(hecksagon|world)\z/
+
+      # Loads the copy's own overlay, then its local files (beside the domain, then in the working
+      # directory), then an environment's overlay, each `.hecksagon` then `.world`, when present.
+      # The environment loads last, so `memory` still wins over a local database.
+      #
+      # @param directory [String] the directory holding the `environments/` folder
+      # @param environment [String, nil] the environment name; nil loads no named overlay
+      # @return [void]
+      def load_overlay(directory, environment)
+        load_each(directory, overlay_files(LOCAL_OVERLAY))
+        [directory, Dir.pwd].uniq.each { |where| load_each(where, LOCAL_FILES) }
+        load_each(directory, overlay_files(environment)) if environment && environment != LOCAL_OVERLAY
+      end
+
+      # The `.hecksagon` and `.world` files of one named overlay, relative to the domain.
+      #
+      # @param name [String] the overlay's name
+      # @return [Array<String>] the two patterns
+      def overlay_files(name)
+        %w[hecksagon world].map { |kind| File.join("environments", "#{name}.#{kind}") }
+      end
+
+      # A local file belongs to the overlay phase, which loads it after the base, so a base glob
+      # such as `*.world` does not pick it up first.
+      #
+      # @param file [String] a file a pattern matched
+      # @param pattern [String] the pattern that matched it
+      # @return [Boolean] whether the file waits for the overlay phase
+      def left_to_overlay?(file, pattern)
+        file.match?(LOCAL_FILE_NAME) && !LOCAL_FILES.include?(pattern)
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/google_authentication.adapter

@@ -0,0 +1,3 @@
+Hecks.adapter "GoogleAuthentication" do
+  port "authentication"
+end

data/lib/hecks/adapters/driven/google_authentication.rb

@@ -0,0 +1,99 @@
+require "securerandom"
+
+require_relative "../../ports/authentication"
+
+module Hecks
+  module Adapters
+    # Google's OIDC handshake — the `authentication` port's adapter for Google
+    # sign-in, via `oauth2` (code exchange) and `google-id-token` (verification).
+    #
+    # `oauth2`/`google-id-token` load lazily, inside the methods that use
+    # them, so a domain that never binds this adapter never needs them installed.
+    #
+    # `GOOGLE_CLIENT_ID`/`GOOGLE_CLIENT_SECRET`/`GOOGLE_REDIRECT_URI` have no
+    # defaults, on purpose: a half-configured login should refuse to boot.
+    module GoogleAuthentication
+      ISSUER = "https://accounts.google.com".freeze
+
+      module_function
+
+      # Builds the OAuth2 client for Google's token endpoints.
+      #
+      # @return [OAuth2::Client] a client configured for Google's OAuth2/OIDC endpoints
+      # @raise [KeyError] if `GOOGLE_CLIENT_ID` or `GOOGLE_CLIENT_SECRET` is unset
+      def client
+        require "oauth2"
+        OAuth2::Client.new(
+          ENV.fetch("GOOGLE_CLIENT_ID"), ENV.fetch("GOOGLE_CLIENT_SECRET"),
+          site:          "https://oauth2.googleapis.com",
+          authorize_url: "https://accounts.google.com/o/oauth2/v2/auth",
+          token_url:     "/token"
+        )
+      end
+
+      # The URL to send a browser to, carrying a fresh CSRF `state` the caller
+      # must stash (typically in a session) and check again in `verify`.
+      #
+      # @return [Array(String, String)] the URL to send the browser to, and the fresh CSRF
+      #   `state` embedded in it
+      # @raise [KeyError] if `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` or
+      #   `GOOGLE_REDIRECT_URI` is unset
+      def authorization_url
+        state = SecureRandom.hex(24)
+        url = client.auth_code.authorize_url(
+          redirect_uri: ENV.fetch("GOOGLE_REDIRECT_URI"),
+          scope:        "openid email profile",
+          state:        state
+        )
+        [url, state]
+      end
+
+      # Exchanges `code` for tokens and verifies the ID token against Google's
+      # JWKS; `email_verified` tells a caller if Google actually checked the email.
+      # @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` handed out before
+      #   the redirect; nil is refused
+      # @return [Hash{Symbol => Object}] `issuer:` and `subject:` (String), `email:` (String,
+      #   or nil if the token carries none), `email_verified:` (Boolean)
+      # @raise [Ports::Authentication::ValidationError] if the state check, code exchange, or
+      #   ID token verification fails
+      # @raise [KeyError] if `GOOGLE_CLIENT_ID` or `GOOGLE_REDIRECT_URI` is unset, or a
+      #   verified token lacks an `iss` or `sub` claim
+      def verify(code:, state:, expected_state:)
+        # Both requires happen up front: the rescue below matches
+        # GoogleIDToken::ValidationError, resolved only when caught, so
+        # requiring it lazily after an OAuth2::Error would mask the real failure.
+        require "oauth2"
+        require "google-id-token"
+
+        raise Ports::Authentication::ValidationError, "state mismatch" unless state && expected_state && state == expected_state
+
+        identity(GoogleIDToken::Validator.new.check(exchange(code), ENV.fetch("GOOGLE_CLIENT_ID")))
+      rescue OAuth2::Error, GoogleIDToken::ValidationError => e
+        raise Ports::Authentication::ValidationError, e.message
+      end
+
+      # Exchanges an authorization code for the provider's raw ID token.
+      #
+      # @param code [String] the authorization code the provider sent back
+      # @return [String] the unverified ID token
+      # @raise [Ports::Authentication::ValidationError] if the response carries no ID token
+      def exchange(code)
+        token = client.auth_code.get_token(code, redirect_uri: ENV.fetch("GOOGLE_REDIRECT_URI"))
+        token.params["id_token"] or raise Ports::Authentication::ValidationError, "no id_token in the response"
+      end
+
+      # Reads the identity claims out of a verified ID token payload.
+      #
+      # @param payload [Hash{String => Object}] the verified token claims
+      # @return [Hash{Symbol => Object}] the same shape `verify` returns
+      def identity(payload)
+        {
+          issuer: payload.fetch("iss"), subject: payload.fetch("sub"),
+          email: payload["email"], email_verified: [true, "true"].include?(payload["email_verified"])
+        }
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/governance_authorization.rb

@@ -3,7 +3,8 @@ require "time"
 module Hecks
   module Adapters
     # The `authorization` port, answered by dispatching queries against Governance's records
-    # in the same registry. Only assignments with no `ends_at` count as live.
+    # in the same registry. Which grants are live is Governance's own declaration, its two
+    # `Live` queries; this reads them and decides nothing about liveness.
     module GovernanceAuthorization
       module_function
 
@@ -18,18 +19,10 @@ module Hecks
       # @param as_of [Integer, nil] Unix epoch seconds; a later (or unparseable) `starts_at` fails
       # @param scope [String, nil] the scope the caller acts in; nil skips the scope check
       # @return [Boolean] true if a live grant of `role` to `actor_id` passes both checks
-      # @raise [Runtime::WiringError] unless exactly one chapter provides `"authorization"`
+      # @raise [Runtime::WiringError] unless exactly one bluebook provides `"authorization"`
       def holds_role?(registry, actor_id:, role:, as_of: nil, scope: nil)
-        rows = Runtime::Dispatcher.new(registry).query(
-          provided_verb(registry, :assignments),
-          actor_id: { value: actor_id.to_s }
-        )
-
-        rows.any? do |row|
-          row[:role_name][:value] == role.to_s &&
-            row[:ends_at].nil? &&
-            in_scope?(row, scope) &&
-            started?(row, as_of)
+        live_assignments(registry, actor_id).any? do |row|
+          row[:role_name][:value] == role.to_s && in_scope?(row, scope) && started?(row, as_of)
         end
       end
 
@@ -43,8 +36,9 @@ module Hecks
         scope.nil? || row[:scope][:value] == scope.to_s
       end
 
-      # `starts_at` is free text, so it is parsed with `Time.parse` rather than compared
-      # lexically. Fails closed: an unparseable value counts as not yet started.
+      # `starts_at` is a UTC date or date-time (the aggregate refuses anything else), parsed with
+      # `Time.parse` to compare against `as_of`. Fails closed on a record that predates that
+      # rule: an unparseable value counts as not yet started.
       #
       # @param row [Hash{Symbol => Object}] one `RoleAssignment` row as
       #   `Runtime::Dispatcher#query` returns it; `:starts_at` holds a `{value: String}` Hash
@@ -61,20 +55,16 @@ module Hecks
 
       # Answers whether one role may act as another.
       #
-      # Read with `.any?` rather than trusting that the exact-pair lookup returns one row.
-      #
       # @param registry [Runtime::Registry] the booted registry
       # @param from_role [String, Symbol] the role the caller holds, compared as a String
       # @param to_role [String, Symbol] the role the caller wants to act as, compared as a String
       # @return [Boolean] true if a live allowance lets `from_role` act as `to_role`
-      # @raise [Runtime::WiringError] unless exactly one chapter provides `"authorization"`
+      # @raise [Runtime::WiringError] unless exactly one bluebook provides `"authorization"`
       def authorized_as?(registry, from_role:, to_role:)
-        rows = Runtime::Dispatcher.new(registry).query(
-          provided_verb(registry, :transitions),
+        Runtime::Dispatcher.new(registry).query(
+          provided_verb(registry, :live_transitions),
           from_role: { value: from_role.to_s }, to_role: { value: to_role.to_s }
-        )
-
-        rows.any? { |row| row[:ends_at].nil? }
+        ).any?
       end
 
       # Returns the actor's live role name, or nil; any fallback is the caller's.
@@ -82,35 +72,41 @@ module Hecks
       # @param registry [Runtime::Registry] the booted registry, to resolve the authorization
       #   provider's verb
       # @param actor_id [String] the actor to look up, compared as a String
-      # @return [String, nil] the role name of the actor's first live (not ended) grant, or
-      #   nil if it has none
-      # @raise [Runtime::WiringError] if the loaded chapters providing `"authorization"` are
+      # @return [String, nil] the role name of the actor's first live grant, or nil if it has none
+      # @raise [Runtime::WiringError] if the loaded bluebooks providing `"authorization"` are
       #   not exactly one (see `provided_verb`)
       def live_role_for(registry, actor_id:)
-        rows = Runtime::Dispatcher.new(registry).query(
-          provided_verb(registry, :assignments),
+        live = live_assignments(registry, actor_id).first
+        live && live[:role_name][:value]
+      end
+
+      # The rows the provider's `live_assignments` query answers for one actor.
+      #
+      # @param registry [Runtime::Registry] the booted registry
+      # @param actor_id [String] the actor, compared as a String
+      # @return [Array<Hash{Symbol => Object}>] the actor's grants that have not ended
+      def live_assignments(registry, actor_id)
+        Runtime::Dispatcher.new(registry).query(
+          provided_verb(registry, :live_assignments),
           actor_id: { value: actor_id.to_s }
         )
-
-        live = rows.find { |row| row[:ends_at].nil? }
-        live && live[:role_name][:value]
       end
 
-      # Reads a verb from the one chapter that `provides "authorization"`; the runtime will
+      # Reads a verb from the one bluebook that `provides "authorization"`; the runtime will
       # not choose between several (as in `Ports::Authorization.adapter`).
       #
       # @param registry [Runtime::Registry] the booted registry to search for the
       #   `"authorization"` provider
-      # @param key [Symbol] which declared verb to read — `:assignments`, `:grant`, or
-      #   `:transitions`
-      # @return [String] the fully-qualified verb the loaded chapter provides for `key`
-      # @raise [Runtime::WiringError] if the loaded chapters providing `"authorization"` are
+      # @param key [Symbol] which declared verb to read: `:live_assignments`, `:live_transitions`,
+      #   `:grant`, or one of the history queries `:assignments` and `:transitions`
+      # @return [String] the fully-qualified verb the loaded bluebook provides for `key`
+      # @raise [Runtime::WiringError] if the loaded bluebooks providing `"authorization"` are
       #   not exactly one
       def provided_verb(registry, key)
         providers = registry.authorization_providers
         unless providers.size == 1
           raise Runtime::WiringError,
-                "#{providers.size} loaded chapters provide \"authorization\"" \
+                "#{providers.size} loaded bluebooks provide \"authorization\"" \
                 "#{" (#{providers.map(&:name).sort.join(", ")})" unless providers.empty?} — " \
                 "a role lookup needs exactly one (framework members declaring it: " \
                 "#{Framework.providers_of(Bluebook::Capabilities::AUTHORIZATION).join(", ")})"

data/lib/hecks/adapters/driven/heki/journal.rb

@@ -41,8 +41,53 @@ module Hecks
           end
         end
 
+        # Reads the chain heads the ledger sealed beside this journal, oldest first.
+        #
+        # A Heki journal has no sequence and is emptied by compaction, so `through:` counts the
+        # entries sealed since the first seal, across compactions.
+        #
+        # @return [Array<Hash>] `through:`, `head:` and `previous:` (the genesis digest first)
+        # @raise [Malformed] if a line of the anchors file is not valid JSON
+        def ledger_anchors
+          return [] unless File.exist?(anchors_path)
+
+          lines = File.readlines(anchors_path, chomp: true).reject(&:empty?)
+          lines.map { |line| anchor_from(JSON.parse(line)) }.sort_by { |anchor| anchor[:through] }
+        rescue JSON::ParserError => e
+          raise Malformed, "#{anchors_path}: json error: #{e.message}"
+        end
+
+        # Seals a chain head beside this journal, one line, fsynced. Sealing the same point twice
+        # with the same head changes nothing; a different head for a sealed point is refused.
+        #
+        # @param through [Integer] how many entries the seals cover in all
+        # @param head [String] the chain digest at `through`
+        # @param previous [String] the head of the seal before this one
+        # @return [void]
+        # @raise [Runtime::WiringError] if the point is already sealed with another head
+        def record_ledger_anchor(through:, head:, previous:)
+          sealed = ledger_anchors.find { |anchor| anchor[:through] == through }
+          if sealed
+            return if sealed[:head] == head
+
+            raise Runtime::WiringError, "#{anchors_path} is already sealed through #{through} with another head"
+          end
+
+          File.open(anchors_path, "ab") do |file|
+            file.write("#{JSON.generate(through: through, head: head, previous: previous)}\n")
+            file.flush
+            file.fsync
+          end
+        end
+
         private
 
+        def anchors_path = "#{@path}.anchors"
+
+        def anchor_from(value)
+          { through: value.fetch("through"), head: value.fetch("head"), previous: value.fetch("previous") }
+        end
+
         def truncate_journal!
           return unless File.exist?(@journal_path)
 

data/lib/hecks/adapters/driven/identity_registry.rb

@@ -16,7 +16,7 @@ module Hecks
       # @return [String, nil] the linked identity's id, or nil if nothing has linked this pair
       def resolve(registry, issuer:, subject:)
         # The verb comes from the declared identity provider (`provides "identity", resolve:`).
-        provider = registry.bluebooks.values.find { |chapter| chapter.provides?(::Hecks::Bluebook::Capabilities::IDENTITY) }
+        provider = registry.bluebooks.values.find { |declaration| declaration.provides?(::Hecks::Bluebook::Capabilities::IDENTITY) }
         verb = provider&.provided_verb(::Hecks::Bluebook::Capabilities::IDENTITY, :resolve) ||
                "Identity::ExternalIdentifier.ResolvedBy"
         rows = Runtime::Dispatcher.new(registry).query(

data/lib/hecks/adapters/driven/in_memory_ordering.rb

@@ -52,7 +52,7 @@ module Hecks
       # @param name [String] an attribute name
       # @return [Boolean] true when `name` is the lifecycle field
       def lifecycle_field?(aggregate, name)
-        aggregate.lifecycle&.field.to_s == name
+        aggregate.lifecycle_field.to_s == name
       end
 
       # Picks the member of a value object that orders it.
@@ -63,8 +63,9 @@ module Hecks
       # @param shape [Bluebook::ValueObject] the value object type
       # @return [String] the member name
       def orderable_member(shape)
+        sole = shape.sole_attribute
         shape.attributes.find { |a| %w[Integer Float].include?(a.type) }&.name ||
-          shape.sole_attribute&.name || "value"
+          sole&.name || "value"
       end
 
       # Resolves the dotted path `FieldPath.dig` should read to compare a value object field.

data/lib/hecks/adapters/driven/key_keeper.rb

@@ -0,0 +1,42 @@
+require_relative "../../runtime/registry"
+require_relative "../../ports/key_vault"
+
+module Hecks
+  module Adapters
+    # The `Keys` port's adapter for a `SubjectKey` (ADR 0142, ADR 0147): has the `key_vault` port
+    # issue a subject's key and destroy it, in the boot whose record asked. A vault that cannot
+    # raises, and the port records the refusal on the subject's key.
+    class KeyKeeper
+      # @param registry [Runtime::Registry] the registry the ask comes from, whose vault adapter
+      #   holds the keys
+      def initialize(registry:)
+        @registry = registry
+      end
+
+      # Issues a key for the subject a record names. The ask is handed that record's held state, in
+      # which the subject is still a one-field value object. The answer names the reference the
+      # vault gave, so the answer event carries it on to the policy that records it.
+      #
+      # @param subject_id [Hash, String] the subject, `{ value: }` as the record holds it
+      # @return [Hash{Symbol => String}] `key_reference:`, the vault's opaque reference
+      def issue(subject_id:, **)
+        { key_reference: Ports::KeyVault.issue(@registry, subject_id: plain(subject_id)) }
+      end
+
+      # Destroys the key a subject's record names. The answer names the key that was destroyed, as
+      # the state held it, so the answer event carries it on to the policy that records it.
+      #
+      # @param key_reference [Hash, String] the vault's opaque reference to the key, `{ value: }`
+      #   as the record holds it
+      # @return [Hash{Symbol => Object}] `key_reference:`, the key that was destroyed
+      def destroy(key_reference:, **)
+        Ports::KeyVault.destroy(@registry, key_reference: plain(key_reference))
+        { key_reference: key_reference }
+      end
+
+      private
+
+      def plain(reference) = reference.is_a?(Hash) ? reference[:value] : reference
+    end
+  end
+end