hecks 5.0.0 → 7.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a6fed3e5b894585b2fa7253696873a4218980f6982b4afeeda5effdd5a4aba4
-  data.tar.gz: b29a6ce60d5ae9142f0b53ee062979397f3c1384ce2f6da8c70b14396425c989
+  metadata.gz: 5513321d2ace0e5e35b6b806fd04f8421e41d713a49667511c278309892a3ec8
+  data.tar.gz: b440aca95a39f41a04375a879b917fd153e6277bba6386a1f637e87c2288f225
 SHA512:
-  metadata.gz: 77b6974a39536f06fd5bffeb121899ca35b1563e5db172bac48dfeef426c445ed459bea60bc004ea29fdb14b14149a72467b61dddce02aa1cc61b2bb9c11b944
-  data.tar.gz: 56fd3680ca94d0060d0ff5e1324c3ccbefb03f5dfc4ac03760cdfb8ee6ad2081c70cef85e4161a66098acb396bdb17c2a485185ff473bee49546a9f0a7336d65
+  metadata.gz: e318b100521c095c1ee8c0962e5108ffe5595281bc9261de0cf8460306c4144b9c5465ef48c6a455c923175b1bc027bcee34d90ea127f5c201d882b427c95169
+  data.tar.gz: 1fede9423b4f0dfd0b95a15d7be5ee3b651d0dfdab3b7430f7f4a3f4292e343c8c9c03babbc8c9d52412a76d38914405190fcf37bdd0ab6090f3d27b005daf1c

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,11 +14,16 @@ Encoding.default_internal = Encoding::UTF_8
 
 $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 
-# 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)
-  require "hecks/cli"
-  exit Hecks::CLI.start(ARGV) unless Hecks::CLI.launcher_form?(ARGV)
+# 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
 
 # These commands keep nothing worth a database, so they run on Memory unless told otherwise.
@@ -28,17 +33,30 @@ MEMORY_COMMANDS = %w[console init interview].freeze
 ENV["HECKS_ENVIRONMENT"] ||= "memory" if MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!"))
 ARGV << "--wait" if MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!")) && !ARGV.include?("--wait")
 
+# A command a ledger answers boots that ledger's directory, not this domain's.
+ledger = { "quality_control" => "qa/bluebook" }.fetch(ARGV.first, nil)
+ARGV.shift if ledger
+
 require "hecks"
+# Every secret a world hands an adapter is masked in whatever this process prints.
+Hecks::Secrets.guard!
 
-# 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__)
+domain = File.expand_path(ledger ? "../#{ledger}" : "../lib/hecks/hecks", __dir__)
 program = "hecks"
 described = begin
   Hecks.describe(domain)
 rescue StandardError => e
-  abort "cannot open Hecks: #{e.message.lines.first.strip}"
+  abort "cannot open Hecks: #{e.message.strip}"
+end
+
+# `hecks usage` reads the local record of what this launcher ran; it boots nothing.
+if ARGV.first == "usage"
+  known = Hecks::Adapters::Driving::CliRunner.known_names(runtime: described, program: program)
+  puts Hecks::Adapters::Driving::UsageLog.summary(known: known)
+  exit 0
 end
 
 text, status, reason = Hecks::Adapters::Driving::CliRunner.usage(
@@ -48,13 +66,13 @@ unless text
   runtime = begin
     Hecks::Adapters::Driving::LauncherOptions.quietly(hold: MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!"))) { Hecks.boot_described(described, install_driving: false) }
   rescue StandardError => e
-    abort "cannot open Hecks: #{e.message.lines.first.strip}"
+    abort "cannot open Hecks: #{e.message.strip}"
   end
   # A question the world lists under `streams`, given `--stream`, tails until interrupted.
   streamed = Hecks::Adapters::Driving::CliRunner.stream(runtime: runtime, argv: ARGV, program: program)
   exit streamed unless streamed.nil?
   text, status, reason = Hecks::Adapters::Driving::CliRunner.call(
-    runtime: runtime, argv: ARGV, program: program
+    runtime: runtime, argv: ARGV, program: program, usage_log: true
   )
 end
 # A `--wait` run that failed answers its settled record on stdout, so `| jq` reads it
@@ -75,4 +93,5 @@ if reason
   exit status
 end
 exit 0 if status.zero? && MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!"))
-status.zero? ? puts(text) : abort(text)
+status.zero? ? puts(text) : warn(text)
+exit status

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": []}.',
@@ -84,8 +84,8 @@ module Hecks
 
       def unwrap(stdout)
         envelope = JSON.parse(stdout)
-        result = envelope["result"]
-        raise Ports::Agent::ValidationError, "no \"result\" in the claude envelope: #{stdout}" unless result
+        result = envelope["result"] if envelope.is_a?(Hash)
+        raise Ports::Agent::ValidationError, "no \"result\" in the claude envelope: #{stdout}" unless result.is_a?(String)
 
         JSON.parse(result)
       rescue JSON::ParserError => e

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,17 @@
 require_relative "../../vocabulary"
+require_relative "../../ports/loading"
+require_relative "../../sentence_form"
+require_relative "folder_overlay"
+require_relative "worktree_overlay"
+require_relative "../../module_folders"
 
 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 +35,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 +69,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 +84,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 +95,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 +108,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 +132,21 @@ module Hecks
         return unless File.directory?(directory)
 
         patterns.each do |pattern|
-          Dir[File.join(directory, pattern)].each { |file| Kernel.load(file) }
+          files_matching(directory, pattern).reject { |file| left_to_overlay?(file, pattern) }.each { |file| load_file(file) }
         end
       end
 
+      # The files `pattern` names under `directory`; the bluebooks of its module folders follow the
+      # directory's own (see ModuleFolders).
+      def files_matching(directory, pattern)
+        found = Dir[File.join(directory, pattern)]
+        found + ModuleFolders.files(directory, pattern.delete_prefix("*"))
+      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 +163,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 +242,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,66 @@
+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/
+
+      # Runs a block with no overlay loaded at all, so a domain read inside it holds only what is
+      # committed: the same on every checkout and in CI, whatever local files this one keeps.
+      #
+      # @return [Object] the block's value
+      def self.committed_only
+        held = Thread.current[:hecks_committed_only]
+        Thread.current[:hecks_committed_only] = true
+        yield
+      ensure
+        Thread.current[:hecks_committed_only] = held
+      end
+
+      # 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)
+        return if Thread.current[:hecks_committed_only]
+
+        WorktreeOverlay.warn_once(directory)
+        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/heki.rb

@@ -133,7 +133,7 @@ module Hecks
       # @param id [String, Object] the record's identity, compared as `id.to_s`
       # @return [Boolean] true when a record was found and deleted, false when there was none
       #   and nothing was journaled
-      def delete(id) # rubocop:disable Naming/PredicateMethod -- the repository port's verb, answering whether a record existed
+      def delete(id)
         return false unless find(id)
 
         entry = Ports::Persistence::Entry.new(operation: "delete", id: id.to_s, state: nil)