hecks 3.4.2 → 3.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d33b33e869c53f5b2c5825c2c9ec8a1a4a2b6dd6fad676b3e9403f314f4bf33
-  data.tar.gz: bc9b6f6509c6e31f6708254ba98e3d2346238ea6d487f25897a1ae5dac2968f0
+  metadata.gz: 3e303214451e949201a80bb0aa29d33e0e8a240e78eda156a4ff6d4913913f20
+  data.tar.gz: de457dd9cd8212c61114a4f6c939479807de32716f0a40cd24c13c51ccaf5a7b
 SHA512:
-  metadata.gz: c53a6ea1c22f5f87116d1a9cf7f432a402cabeb1b2f8c7a9d199bc7e1adfc46bcb0f3d391435138f1d20423e10d1047fba5d673fc9d00087d36b44fa5218e956
-  data.tar.gz: a9945ea4ddb39bfb0876eecf5d2b699c34f77e565333b60435fe626d492b9befedbd0fc7aaa81c91b6c48cd74ace82d884e482a535697cd0c256eafd896ef924
+  metadata.gz: a35c1b98ca37e475d237288e1c7670ed7ecc32ad8b91a2c3fc6c3a010973673a5441755e3fda5bc2f2b84b2dfeaee2d873276ea14043ea787e959aebc5706130
+  data.tar.gz: 54222db25bfab9416ef092b467a243fac8df095997274f69be0f3105b1edf6cd39fb2b86b87360bf5a270ddbb62e53bc2c3b6db2dd840f93743e49c12085ef67

data/examples/pizzas/bluebook/hecksagon/mock_stripe_payment_adapter.rb

@@ -33,4 +33,4 @@ RUNTIME.dispatch_port(
 
 sold = Order.find(NAME)
 puts "After payment:  #{sold.status}, customer=#{sold.customer_name.to_h}"
-puts "Events: #{sold.events.map(&:name).join(', ')}"
+puts "Events: #{sold.events.map(&:name).join(", ")}"

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

@@ -62,13 +62,7 @@ module Hecks
 
       # Argv spawn, never a shell, so a `claude` shell alias cannot apply; no tools are allowed.
       def call(system:, payload:)
-        stdout, status = Timeout.timeout(TIMEOUT_SECONDS) do
-          Open3.capture2(
-            "claude", "-p", "--output-format", "json",
-            "--append-system-prompt", system, "--allowedTools", "",
-            stdin_data: JSON.generate(payload)
-          )
-        end
+        stdout, status = spawn_claude(system, payload)
         raise Ports::Agent::Unavailable, "claude exited #{status.exitstatus}: #{stdout}" unless status.success?
 
         unwrap(stdout)
@@ -78,6 +72,16 @@ module Hecks
         raise Ports::Agent::Unavailable, "claude is not on PATH: #{e.message}"
       end
 
+      def spawn_claude(system, payload)
+        Timeout.timeout(TIMEOUT_SECONDS) do
+          Open3.capture2(
+            "claude", "-p", "--output-format", "json",
+            "--append-system-prompt", system, "--allowedTools", "",
+            stdin_data: JSON.generate(payload)
+          )
+        end
+      end
+
       def unwrap(stdout)
         envelope = JSON.parse(stdout)
         result = envelope["result"]

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

@@ -0,0 +1,90 @@
+require "json"
+require "net/http"
+require "uri"
+
+require_relative "../../../runtime/errors"
+
+module Hecks
+  module Adapters
+    class D1
+      # HTTP transport exposing the slice of `SQLite3::Database` the shared SQLite code uses.
+      class Connection
+        ENDPOINT = "https://api.cloudflare.com/client/v4".freeze
+
+        def initialize(account_id:, database_id:, api_token:)
+          @uri = URI("#{ENDPOINT}/accounts/#{account_id}/d1/database/#{database_id}/query")
+          @api_token = api_token
+        end
+
+        def execute(sql, binds = [])
+          response_results({ sql: sql, params: binds }).first.fetch("results", [])
+        end
+
+        # D1 batches are transactions: statements run in order and a failure rolls all back.
+        def batch(statements)
+          payload = {
+            batch: statements.map do |sql, binds|
+              { sql: sql, params: binds || [] }
+            end
+          }
+          response_results(payload).map { |result| result.fetch("results", []) }
+        end
+
+        def get_first_row(sql, binds = [])
+          execute(sql, binds).first
+        end
+
+        def get_first_value(sql, binds = [])
+          get_first_row(sql, binds)&.values&.first
+        end
+
+        private
+
+        def response_results(payload)
+          response = post(payload)
+          body = parse_d1_body(response)
+          messages = (body["errors"] || []).map { |error| error["message"] }.join("; ")
+
+          raise Runtime::WiringError, "D1 query failed: #{messages.empty? ? response.body : messages}" unless body["success"]
+
+          refuse_failed_statement(body.fetch("result"), messages)
+        end
+
+        def post(payload)
+          request = Net::HTTP::Post.new(@uri)
+          request["Authorization"] = "Bearer #{@api_token}"
+          request["Content-Type"] = "application/json"
+          request.body = JSON.generate(payload)
+
+          Net::HTTP.start(@uri.host, @uri.port, use_ssl: true) { |http| http.request(request) }
+        end
+
+        def refuse_failed_statement(results, messages)
+          failed = results.find { |result| result["success"] == false }
+          raise Runtime::WiringError, "D1 query failed: #{failed_statement_detail(failed, messages)}" if failed
+
+          results
+        end
+
+        def parse_d1_body(response)
+          JSON.parse(response.body)
+        rescue JSON::ParserError
+          raise Runtime::WiringError, "D1 query failed: non-JSON response (HTTP #{response.code}): #{response.body}"
+        end
+
+        # Prefers the statement's own error/message (by key presence) over the whole-response one.
+        def failed_statement_detail(failed, messages)
+          detail =
+            if failed.key?("error")
+              failed["error"]
+            elsif failed.key?("message")
+              failed["message"]
+            else
+              messages
+            end
+          detail.to_s.empty? ? "a batched statement failed" : detail
+        end
+      end
+    end
+  end
+end

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

@@ -1,11 +1,14 @@
 require "json"
-require "net/http"
-require "uri"
 
 require_relative "sql_query_builder"
 require_relative "sqlite/schema_builder"
 require_relative "sqlite/codec"
+require_relative "sqlite/dialect"
+require_relative "sqlite/events"
+require_relative "sqlite/repository"
+require_relative "sqlite/sagas"
 require_relative "sqlite"
+require_relative "d1/connection"
 require_relative "../../ports/persistence/append_only"
 require_relative "../../query_specification/common/null_policy"
 require_relative "../../query_specification/common/order_by"
@@ -18,83 +21,13 @@ module Hecks
     # Cloudflare D1 (managed SQLite over REST): reuses Sqlite's schema and codec unchanged.
     # Only the transport differs, one HTTP call per query.
     class D1
-      # HTTP transport exposing the slice of `SQLite3::Database` the shared SQLite code uses.
-      class Connection
-        ENDPOINT = "https://api.cloudflare.com/client/v4".freeze
-
-        def initialize(account_id:, database_id:, api_token:)
-          @uri = URI("#{ENDPOINT}/accounts/#{account_id}/d1/database/#{database_id}/query")
-          @api_token = api_token
-        end
-
-        def execute(sql, binds = [])
-          response_results({ sql: sql, params: binds }).first.fetch("results", [])
-        end
-
-        # D1 batches are transactions: statements run in order and a failure rolls all back.
-        def batch(statements)
-          payload = {
-            batch: statements.map do |sql, binds|
-              { sql: sql, params: binds || [] }
-            end
-          }
-          response_results(payload).map { |result| result.fetch("results", []) }
-        end
-
-        private
-
-        def response_results(payload)
-          request = Net::HTTP::Post.new(@uri)
-          request["Authorization"] = "Bearer #{@api_token}"
-          request["Content-Type"] = "application/json"
-          request.body = JSON.generate(payload)
-
-          response = Net::HTTP.start(@uri.host, @uri.port, use_ssl: true) { |http| http.request(request) }
-          body = parse_d1_body(response)
-          messages = (body["errors"] || []).map { |error| error["message"] }.join("; ")
-
-          raise Runtime::WiringError, "D1 query failed: #{messages.empty? ? response.body : messages}" unless body["success"]
-
-          results = body.fetch("result")
-          failed = results.find { |result| result["success"] == false }
-          raise Runtime::WiringError, "D1 query failed: #{failed_statement_detail(failed, messages)}" if failed
-
-          results
-        end
-
-        def parse_d1_body(response)
-          JSON.parse(response.body)
-        rescue JSON::ParserError
-          raise Runtime::WiringError, "D1 query failed: non-JSON response (HTTP #{response.code}): #{response.body}"
-        end
-
-        # Prefers the statement's own error/message (by key presence) over the whole-response one.
-        def failed_statement_detail(failed, messages)
-          detail =
-            if failed.key?("error")
-              failed["error"]
-            elsif failed.key?("message")
-              failed["message"]
-            else
-              messages
-            end
-          detail.to_s.empty? ? "a batched statement failed" : detail
-        end
-
-        public
-
-        def get_first_row(sql, binds = [])
-          execute(sql, binds).first
-        end
-
-        def get_first_value(sql, binds = [])
-          get_first_row(sql, binds)&.values&.first
-        end
-      end
-
       include SqlQueryBuilder
       include Sqlite::SchemaBuilder
       include Sqlite::Codec
+      include Sqlite::Repository
+      include Sqlite::Events
+      include Sqlite::Sagas
+      include Sqlite::Dialect
 
       SQL_TYPES = { "Integer" => "INTEGER", "Float" => "REAL" }.freeze
 
@@ -107,25 +40,9 @@ module Hecks
       # @raise [Runtime::WiringError] if a required setting is missing or empty
       def initialize(aggregate:, settings: {}, root: nil)
         @aggregate = aggregate
-
-        account_id  = settings.key?(:account_id)  ? settings[:account_id]  : settings["account_id"]
-        database_id = settings.key?(:database_id) ? settings[:database_id] : settings["database_id"]
-        api_token   = settings.key?(:api_token)   ? settings[:api_token]   : settings["api_token"]
-        { "account_id" => account_id, "database_id" => database_id, "api_token" => api_token }.each do |name, value|
-          raise Runtime::WiringError, "D1 needs a #{name.inspect} in its world settings" if value.to_s.empty?
-        end
-
-        @db = Connection.new(account_id: account_id, database_id: database_id, api_token: api_token)
+        @db = connect(settings)
         # Saga rows are scoped by domain; one D1 database per domain, so aggregates share it.
-        @domain = (
-          if settings.key?(:domain)
-            settings[:domain]
-          elsif settings.key?("domain")
-            settings["domain"]
-          else
-            aggregate.name
-          end
-        ).to_s
+        @domain = setting(settings, :domain, aggregate.name).to_s
 
         # No PRAGMA synchronous: D1 is managed and its query endpoint disallows PRAGMA writes.
         create_aggregate_table!
@@ -138,35 +55,6 @@ module Hecks
 
       def table = @aggregate.storage_name
 
-      def find(id)
-        row = @db.get_first_row("SELECT * FROM #{quoted_table} WHERE id = ?", [id.to_s])
-        return nil unless row
-
-        Runtime::Instance.new(aggregate: @aggregate, id: row["id"], state: decode(row))
-      end
-
-      # Lists every record, ordered by id or by `order_by` when it names an attribute.
-      # @raise [Runtime::WiringError] if `order_by` names no attribute of the aggregate
-      def all(order_by: nil, direction: :asc)
-        order_sql = "ORDER BY id"
-        if order_by
-          name = order_by.to_s.split(".").first
-          unless @aggregate.lifecycle&.field.to_s == name || @aggregate.attribute(name)
-            raise Runtime::WiringError,
-                  "#{@aggregate.name} has no attribute #{order_by.inspect} to order by"
-          end
-
-          spec = QuerySpecification::Common::OrderBy.new(field: order_by, direction: direction)
-          order_sql = "ORDER BY #{order_clause(spec, nil)}"
-        end
-
-        @db.execute("SELECT * FROM #{quoted_table} #{order_sql}").map do |row|
-          Runtime::Instance.new(aggregate: @aggregate, id: row["id"], state: decode(row))
-        end
-      end
-
-      def count = @db.get_first_value("SELECT COUNT(*) FROM #{quoted_table}").to_i
-
       def append(entry)
         @db.execute(
           "INSERT INTO #{quoted_entry_table} (aggregate_id, operation, state, mirrors) VALUES (?, ?, ?, ?)",
@@ -176,21 +64,6 @@ module Hecks
         entry
       end
 
-      def project(entry)
-        return @db.execute("DELETE FROM #{quoted_table} WHERE id = ?", [entry.id]) if entry.delete?
-
-        instance = Runtime::Instance.new(aggregate: @aggregate, id: entry.id, state: entry.state)
-        columns = (["id"] + persisted_fields.map { |field| field[:name].to_s }).map { |c| quote_ident(c) }
-        values  = [instance.id.to_s] + persisted_fields.map { |field| encode_field(field, instance[field[:name]]) }
-        slots   = Array.new(columns.size, "?").join(", ")
-
-        @db.execute(
-          "INSERT OR REPLACE INTO #{quoted_table} (#{columns.join(', ')}) VALUES (#{slots})",
-          values
-        )
-        instance
-      end
-
       # The whole journal in append order, for `AppendOnly#recover!` to replay.
       def entries
         @db.execute("SELECT aggregate_id, operation, state, mirrors FROM #{quoted_entry_table} ORDER BY sequence").map do |row|
@@ -204,13 +77,6 @@ module Hecks
         end
       end
 
-      # Clears the aggregate table and its journal; events and saga rows stay.
-      def reset!
-        @db.execute("DELETE FROM #{quoted_table}")
-        @db.execute("DELETE FROM #{quoted_entry_table}")
-        self
-      end
-
       # Journals then projects as two HTTP requests; the journal row stays if projecting fails.
       def save(instance)
         entry = Ports::Persistence::Entry.new(operation: "save", id: instance.id.to_s, state: instance.state.dup)
@@ -223,196 +89,64 @@ module Hecks
       # The existence check is the batch's first statement and both writes are gated by
       # WHERE NOT EXISTS, so `insert_only` has no gap between check and write.
       # @return [Symbol] `:conflicted` only when `insert_only` met an existing row
-      # rubocop:disable-next Metrics/AbcSize
-      # rubocop:disable-next Metrics/MethodLength
       def atomic_put(entry, insert_only: false)
-        instance = Runtime::Instance.new(aggregate: @aggregate, id: entry.id, state: entry.state)
-        columns = (["id"] + persisted_fields.map { |field| field[:name].to_s }).map { |column| quote_ident(column) }
-        values = [instance.id.to_s] + persisted_fields.map { |field| encode_field(field, instance[field[:name]]) }
-        slots = Array.new(columns.size, "?").join(", ")
-        not_exists = "WHERE NOT EXISTS (SELECT 1 FROM #{quoted_table} WHERE id = ?)"
-
-        status_sql =
-          if insert_only
-            "SELECT CASE WHEN EXISTS (SELECT 1 FROM #{quoted_table} WHERE id = ?) " \
-              "THEN 'conflicted' ELSE 'inserted' END AS status"
-          else
-            "SELECT CASE WHEN EXISTS (SELECT 1 FROM #{quoted_table} WHERE id = ?) " \
-              "THEN 'replaced' ELSE 'inserted' END AS status"
-          end
-
-        # `mirrors` is nullable; see `append`.
-        encoded_mirrors = entry.mirrors && JSON.generate(entry.mirrors)
-
-        entry_sql, entry_binds =
-          if insert_only
-            [
-              "INSERT INTO #{quoted_entry_table} (aggregate_id, operation, state, mirrors) " \
-              "SELECT ?, ?, ?, ? #{not_exists}",
-              [entry.id, entry.operation, state_json(entry.state), encoded_mirrors, entry.id.to_s]
-            ]
-          else
-            [
-              "INSERT INTO #{quoted_entry_table} (aggregate_id, operation, state, mirrors) VALUES (?, ?, ?, ?)",
-              [entry.id, entry.operation, state_json(entry.state), encoded_mirrors]
-            ]
-          end
-
-        aggregate_sql, aggregate_binds =
-          if insert_only
-            [
-              "INSERT INTO #{quoted_table} (#{columns.join(', ')}) SELECT #{slots} #{not_exists}",
-              values + [entry.id.to_s]
-            ]
-          else
-            [
-              "INSERT OR REPLACE INTO #{quoted_table} (#{columns.join(', ')}) VALUES (#{slots})",
-              values
-            ]
-          end
-
-        results = @db.batch([
-                              [status_sql, [entry.id.to_s]],
-                              [entry_sql, entry_binds],
-                              [aggregate_sql, aggregate_binds]
-                            ])
-
+        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
       end
 
-      def delete(id)
-        entry = Ports::Persistence::Entry.new(operation: "delete", id: id.to_s, state: nil)
-        append(entry)
-        project(entry)
-        true
-      end
-
-      def record_event(event)
-        @db.execute(
-          "INSERT INTO events (name, aggregate, aggregate_id, payload, occurred_at) VALUES (?, ?, ?, ?, ?)",
-          [event.name, event.aggregate, event.id.to_s, JSON.generate(event.payload), event.occurred_at]
-        )
-      end
-
-      # Every recorded event in the shared `events` table, not only this aggregate's.
-      def events
-        @db.execute("SELECT * FROM events ORDER BY id").map do |row|
-          Runtime::Event.new(
-            name:        row["name"],
-            aggregate:   row["aggregate"],
-            id:          row["aggregate_id"],
-            payload:     JSON.parse(row["payload"], symbolize_names: true),
-            occurred_at: row["occurred_at"]
-          )
-        end
-      end
+      private
 
-      # One record's recorded events, oldest first — pushed down as a `WHERE` clause
-      # (`hecks_events_aggregate_id_idx`) instead of filtering `#events`'s whole-table read.
-      def events_for(aggregate:, id:)
-        @db.execute(
-          "SELECT * FROM events WHERE aggregate = ? AND aggregate_id = ? ORDER BY id",
-          [aggregate, id.to_s]
-        ).map do |row|
-          Runtime::Event.new(
-            name:        row["name"],
-            aggregate:   row["aggregate"],
-            id:          row["aggregate_id"],
-            payload:     JSON.parse(row["payload"], symbolize_names: true),
-            occurred_at: row["occurred_at"]
-          )
+      # The settings are read under a Symbol or a String key; each credential is required.
+      def connect(settings)
+        credentials = %w[account_id database_id api_token].to_h { |name| [name, setting(settings, name.to_sym, nil)] }
+        credentials.each do |name, value|
+          raise Runtime::WiringError, "D1 needs a #{name.inspect} in its world settings" if value.to_s.empty?
         end
-      end
 
-      # Persists a saga's checkpointed state as one D1 statement.
-      #
-      # @param process_manager [String, Symbol] the process manager's name
-      # @param correlation [String, Object] the instance's correlation value, stored as
-      #   `correlation.to_s`
-      # @param state [String, Symbol] the saga's current state name
-      # @param memory [Hash] the saga's memory; must be JSON-serializable
-      # @param completed_compensations [Array] the ledger of completed compensable legs; must
-      #   be JSON-serializable
-      # @return [Array] the statement's empty result rows; callers ignore it
-      # @raise [Runtime::WiringError] if D1 rejects the statement
-      def save_saga(process_manager:, correlation:, state:, memory:, completed_compensations: [])
-        @db.execute(
-          "INSERT OR REPLACE INTO hecks_saga_instances (domain, process_manager, correlation, state, memory, " \
-          "completed_compensations) VALUES (?, ?, ?, ?, ?, ?)",
-          [@domain, process_manager.to_s, correlation.to_s, state.to_s, JSON.generate(memory),
-           JSON.generate(completed_compensations)]
-        )
-      end
-
-      def delete_saga(process_manager:, correlation:)
-        @db.execute(
-          "DELETE FROM hecks_saga_instances WHERE domain = ? AND process_manager = ? AND correlation = ?",
-          [@domain, process_manager.to_s, correlation.to_s]
-        )
-      end
-
-      # Yields each checkpointed saga of this domain, for `Registry#rehydrate_sagas!`.
-      def each_saga
-        return enum_for(:each_saga) unless block_given?
-
-        @db.execute(
-          "SELECT process_manager, correlation, state, memory, completed_compensations " \
-          "FROM hecks_saga_instances WHERE domain = ?",
-          [@domain]
-        ).each do |row|
-          yield row["process_manager"], row["correlation"], row["state"],
-                JSON.parse(row["memory"], symbolize_names: true),
-                JSON.parse(row["completed_compensations"] || "[]", symbolize_names: true)
-        end
+        Connection.new(account_id: credentials["account_id"], database_id: credentials["database_id"],
+                       api_token: credentials["api_token"])
       end
 
-      private
-
-      # SqlQueryBuilder dialect hooks, copied from Sqlite's private methods.
-      def select_list = "*"
-      def from_relation = quoted_table
-      def dialect_name = "D1"
-      def empty_in_clause = "0"
+      # A setting read under its Symbol key, then its String key, then `default`.
+      def setting(settings, key, default)
+        return settings[key] if settings.key?(key)
+        return settings[key.to_s] if settings.key?(key.to_s)
 
-      def placeholder(binds, value)
-        binds << value
-        "?"
+        default
       end
 
-      def contains_clause(expression, placeholder)
-        "instr(#{expression}, #{placeholder}) > 0"
+      # The batch's first statement: what the put will do, decided against the current row.
+      def status_statement(entry, insert_only)
+        outcome = insert_only ? "conflicted" : "replaced"
+        sql = "SELECT CASE WHEN EXISTS (SELECT 1 FROM #{quoted_table} WHERE id = ?) " \
+              "THEN '#{outcome}' ELSE 'inserted' END AS status"
+        [sql, [entry.id.to_s]]
       end
 
-      def list_contains_clause(column, member, placeholder)
-        target = member.empty? ? "json_each.value" : "json_extract(json_each.value, '$.#{member}')"
-        "EXISTS (SELECT 1 FROM json_each(#{quote_ident(column)}) WHERE #{target} = #{placeholder})"
-      end
-
-      def plain_column(name) = quote_ident(name)
+      def entry_statement(entry, insert_only)
+        # `mirrors` is nullable; see `append`.
+        binds = [entry.id, entry.operation, state_json(entry.state), entry.mirrors && JSON.generate(entry.mirrors)]
+        head = "INSERT INTO #{quoted_entry_table} (aggregate_id, operation, state, mirrors) "
+        return ["#{head}VALUES (?, ?, ?, ?)", binds] unless insert_only
 
-      def nested_expression(name, path, member)
-        json_path = path.empty? ? "$.#{member || 'value'}" : "$.#{path.join('.')}"
-        "json_extract(#{quote_ident(name)}, '#{json_path}')"
+        ["#{head}SELECT ?, ?, ?, ? #{not_exists_sql}", binds + [entry.id.to_s]]
       end
 
-      # SQLite has no bare OFFSET; LIMIT -1 is its unbounded spelling.
-      def unbounded_limit = " LIMIT -1"
-
-      def order_clause(order_by, policy)
-        QuerySpecification::Common::NullPolicy.sql_order(query_expression(order_by.field), order_by.direction, policy)
-      end
+      def aggregate_statement(entry, insert_only)
+        instance = Runtime::Instance.new(aggregate: @aggregate, id: entry.id, state: entry.state)
+        columns = quoted_columns
+        values = instance_values(instance)
+        return [upsert_sql(columns), values] unless insert_only
 
-      def execute_query(sql, binds)
-        @db.execute(sql, binds).map { |row| Runtime::Instance.new(aggregate: @aggregate, id: row["id"], state: decode(row)) }
+        slots = Array.new(columns.size, "?").join(", ")
+        ["INSERT INTO #{quoted_table} (#{columns.join(", ")}) SELECT #{slots} #{not_exists_sql}", values + [entry.id.to_s]]
       end
 
-      def quote_ident(name)
-        %("#{name.to_s.gsub('"', '""')}")
-      end
+      def not_exists_sql = "WHERE NOT EXISTS (SELECT 1 FROM #{quoted_table} WHERE id = ?)"
 
-      def quoted_table = quote_ident(table)
-      def entry_table = "#{table}_entries"
-      def quoted_entry_table = quote_ident(entry_table)
+      def dialect_name = "D1"
     end
   end
 end

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

@@ -57,6 +57,15 @@ module Hecks
           load_each(directory, DOMAIN_ORDER)
         end
 
+        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")])
@@ -86,21 +95,22 @@ module Hecks
       # @return [void]
       def load_selected(files, environment: nil)
         bluebooks, rest = files.partition { |f| f.end_with?(".bluebook") }
-
-        if bluebooks.any?
-          Bluebook::MetaValidator.defer { bluebooks.sort.each { |f| Kernel.load(f) } }
-          Bluebook::MetaValidator.judge_deferred!(Hecks.current_registry)
-        end
-
+        load_selected_bluebooks(bluebooks)
         %w[.hecksagon .world].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
+      end
 
-        return unless environment
+      # Loads the given bluebook files as one deferred group, judged once after all are loaded.
+      #
+      # @param bluebooks [Array<String>] bluebook file paths; none means nothing loads
+      # @return [void]
+      def load_selected_bluebooks(bluebooks)
+        return if bluebooks.empty?
 
-        directory = File.dirname(files.first)
-        load_each(directory, [File.join("environments", "#{environment}.hecksagon")])
-        load_each(directory, [File.join("environments", "#{environment}.world")])
+        Bluebook::MetaValidator.defer { bluebooks.sort.each { |f| Kernel.load(f) } }
+        Bluebook::MetaValidator.judge_deferred!(Hecks.current_registry)
       end
 
       # Loads every file under `directory` matching any of `patterns`, in pattern order.

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

@@ -69,16 +69,30 @@ module Hecks
 
         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"))
-        id_token = token.params["id_token"] or raise Ports::Authentication::ValidationError, "no id_token in the response"
+        token.params["id_token"] or raise Ports::Authentication::ValidationError, "no id_token in the response"
+      end
 
-        payload = GoogleIDToken::Validator.new.check(id_token, ENV.fetch("GOOGLE_CLIENT_ID"))
+      # 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"])
         }
-      rescue OAuth2::Error, GoogleIDToken::ValidationError => e
-        raise Ports::Authentication::ValidationError, e.message
       end
     end
   end