hecks 2.8.0 → 3.0.0

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

@@ -5,7 +5,7 @@ require "uri"
 require_relative "sql_query_builder"
 require_relative "sqlite/schema_builder"
 require_relative "sqlite/codec"
-require_relative "sqlite" # for Sqlite::SchemaBuilder/Sqlite::Codec — see the reuse note below
+require_relative "sqlite"
 require_relative "../../ports/persistence/append_only"
 require_relative "../../query_specification/common/null_policy"
 require_relative "../../query_specification/common/order_by"
@@ -15,59 +15,23 @@ require_relative "../../runtime/instance"
 
 module Hecks
   module Adapters
-    # Cloudflare D1 — SQLite, managed, reached over its REST API rather
-    # than a local file. D1 is SQLite, dialect and all, so this file
-    # reuses Sqlite::SchemaBuilder and Sqlite::Codec unchanged (the DDL
-    # and the column encode/decode) and SqlQueryBuilder's dialect hooks
-    # are copied near-verbatim from sqlite.rb — the only real difference
-    # is the transport (D1::Connection, an HTTP call per query, vs a
-    # persistent local sqlite3 handle). See sqlite.rb's own header
-    # comment: "this file supplies only SQLite's dialect" — true here too.
+    # Cloudflare D1 (managed SQLite over REST): reuses Sqlite's schema and codec unchanged.
+    # Only the transport differs, one HTTP call per query.
     class D1
-      # **The transport** — mirrors just the slice of SQLite3::Database's own
-      # interface (execute/get_first_row/get_first_value, rows as
-      # column-name-keyed hashes) that Sqlite::SchemaBuilder, Sqlite::Codec,
-      # and this file's own methods already assume. One stateless HTTP call
-      # per execute, not a persistent connection — D1 has no connection to
-      # hold open.
+      # HTTP transport exposing the slice of `SQLite3::Database` the shared SQLite code uses.
       class Connection
         ENDPOINT = "https://api.cloudflare.com/client/v4".freeze
 
-        # @param account_id [String] the Cloudflare account that owns the database
-        # @param database_id [String] the D1 database's id
-        # @param api_token [String] a Cloudflare API token, sent as a bearer token on every
-        #   request
         def initialize(account_id:, database_id:, api_token:)
           @uri = URI("#{ENDPOINT}/accounts/#{account_id}/d1/database/#{database_id}/query")
           @api_token = api_token
         end
 
-        # Runs one statement in its own HTTP request and returns its rows.
-        #
-        # @param sql [String] the statement, with `?` placeholders
-        # @param binds [Array<Object>] one value per placeholder, in order
-        # @return [Array<Hash{String => Object}>] the result rows keyed by column name; `[]`
-        #   for a statement that returns none
-        # @raise [Runtime::WiringError] if D1 reports the query failed or answers with a body
-        #   that is not JSON
         def execute(sql, binds = [])
           response_results({ sql: sql, params: binds }).first.fetch("results", [])
         end
 
-        # Runs several statements as one transaction in a single HTTP request.
-        #
-        # D1 batches are SQL transactions: statements execute in order and a
-        # failure rolls the entire sequence back. Keep the tuple-shaped local
-        # seam small so adapter code and focused fakes do not need to know the
-        # REST request envelope.
-        # https://developers.cloudflare.com/d1/worker-api/d1-database/#batch
-        #
-        # @param statements [Array<Array(String, Array)>] `[sql, binds]` pairs in execution
-        #   order; nil binds mean none
-        # @return [Array<Array<Hash{String => Object}>>] each statement's result rows, in
-        #   the order given
-        # @raise [Runtime::WiringError] if D1 reports the request or any one statement failed,
-        #   or answers with a body that is not JSON
+        # D1 batches are transactions: statements run in order and a failure rolls all back.
         def batch(statements)
           payload = {
             batch: statements.map do |sql, binds|
@@ -104,11 +68,7 @@ module Hecks
           raise Runtime::WiringError, "D1 query failed: non-JSON response (HTTP #{response.code}): #{response.body}"
         end
 
-        # `messages` is the whole-response :errors fallback, tried last —
-        # a per-statement `failed["error"]`/`failed["message"]` (checked
-        # by key presence, not truthiness, so an explicit `nil` still
-        # counts as "the key was there") is always more specific to which
-        # statement failed, when either is present.
+        # 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")
@@ -123,26 +83,10 @@ module Hecks
 
         public
 
-        # Runs one statement and keeps only its first row, as `SQLite3::Database` does.
-        #
-        # @param sql [String] the statement, with `?` placeholders
-        # @param binds [Array<Object>] one value per placeholder, in order
-        # @return [Hash{String => Object}, nil] the first row keyed by column name, or nil when
-        #   the statement returned none
-        # @raise [Runtime::WiringError] if D1 reports the query failed or answers with a body
-        #   that is not JSON
         def get_first_row(sql, binds = [])
           execute(sql, binds).first
         end
 
-        # Runs one statement and keeps only the first column of its first row.
-        #
-        # @param sql [String] the statement, with `?` placeholders
-        # @param binds [Array<Object>] one value per placeholder, in order
-        # @return [Object, nil] the value as D1's JSON carries it, or nil when the statement
-        #   returned no row
-        # @raise [Runtime::WiringError] if D1 reports the query failed or answers with a body
-        #   that is not JSON
         def get_first_value(sql, binds = [])
           get_first_row(sql, binds)&.values&.first
         end
@@ -156,22 +100,11 @@ module Hecks
 
       attr_reader :aggregate
 
-      # Names the optional persistence capabilities `Ports::Persistence::AppendOnly` may rely on.
-      #
-      # @return [Array<Symbol>] `[:atomic_put]`
       def persistence_capabilities = [:atomic_put]
 
-      # Checks the credentials are declared and creates the aggregate, journal, event and
-      # saga tables if absent, one HTTP request per statement.
-      #
-      # @param aggregate [Bluebook::Aggregate] the aggregate whose table this adapter owns
-      # @param settings [Hash{Symbol, String => Object}] world settings for the binding:
-      #   `account_id`, `database_id` and `api_token` (all required) and `domain` (scopes saga
-      #   rows, default the aggregate's name), each read under a Symbol or a String key
-      # @param root [String, nil] project root directory; accepted for the shared adapter
-      #   constructor shape and ignored
-      # @raise [Runtime::WiringError] if a required setting is missing or empty, or D1 rejects
-      #   a table-creation statement
+      # Creates the aggregate, journal, event and saga tables if absent.
+      # Settings: `account_id`, `database_id`, `api_token` (required) and `domain` (saga scope).
+      # @raise [Runtime::WiringError] if a required setting is missing or empty
       def initialize(aggregate:, settings: {}, root: nil)
         @aggregate = aggregate
 
@@ -183,12 +116,7 @@ module Hecks
         end
 
         @db = Connection.new(account_id: account_id, database_id: database_id, api_token: api_token)
-        # The optional saga-persistence capability's own scoping column
-        # (§2/§4) — D1's domain isolation is by whole-database identity
-        # (one D1 database per domain in practice), so unlike Sqlite's
-        # own per-aggregate-file default, there's no "which file does
-        # this end up in" ambiguity here: every aggregate on D1 within a
-        # domain already shares one database.
+        # Saga rows are scoped by domain; one D1 database per domain, so aggregates share it.
         @domain = (
           if settings.key?(:domain)
             settings[:domain]
@@ -199,9 +127,7 @@ module Hecks
           end
         ).to_s
 
-        # No PRAGMA synchronous here, unlike Sqlite — D1 is a managed
-        # durable service; there is no local fsync policy for a caller to
-        # tune, and the query endpoint has no PRAGMA write-access to it.
+        # No PRAGMA synchronous: D1 is managed and its query endpoint disallows PRAGMA writes.
         create_aggregate_table!
         create_entry_table!
         ensure_entry_operation_column!
@@ -210,16 +136,8 @@ module Hecks
         create_saga_table!
       end
 
-      # Names the aggregate's table; the journal table is keyed off it.
-      #
-      # @return [String] the aggregate's snake_case storage name, unquoted
       def table = @aggregate.storage_name
 
-      # Reads the current row for one aggregate identity.
-      #
-      # @param id [String, Object] the aggregate identity, bound as `id.to_s`
-      # @return [Runtime::Instance, nil] the decoded record, or nil when no row has that id
-      # @raise [Runtime::WiringError] if D1 rejects the statement
       def find(id)
         row = @db.get_first_row("SELECT * FROM #{quoted_table} WHERE id = ?", [id.to_s])
         return nil unless row
@@ -227,19 +145,8 @@ module Hecks
         Runtime::Instance.new(aggregate: @aggregate, id: row["id"], state: decode(row))
       end
 
-      # Lists every stored record, ordered by id unless an ordering attribute is given.
-      #
-      # order_by is a runtime value — see postgres.rb's own all for the
-      # full reasoning; whitelisted the identical way, same order_clause
-      # Sqlite's own all reuses (D1 speaks the identical dialect).
-      #
-      # @param order_by [String, Symbol, nil] attribute (or dotted value-object path) to sort
-      #   by, with id as the tie-break; nil orders by id alone
-      # @param direction [Symbol, String] `:asc` or `:desc`, case-insensitive; anything else
-      #   sorts ascending
-      # @return [Array<Runtime::Instance>] the decoded records, `[]` when the table is empty
-      # @raise [Runtime::WiringError] if `order_by` names no attribute of the aggregate, or D1
-      #   rejects the statement
+      # 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
@@ -258,37 +165,17 @@ module Hecks
         end
       end
 
-      # Counts the rows in the aggregate's table, deleted records excluded.
-      #
-      # @return [Integer] number of current records
-      # @raise [Runtime::WiringError] if D1 rejects the statement
       def count = @db.get_first_value("SELECT COUNT(*) FROM #{quoted_table}").to_i
 
-      # Inserts one journal row in its own HTTP request.
-      #
-      # @param entry [Ports::Persistence::Entry] the save or delete to journal; `state` is
-      #   encoded through the state codec and `mirrors` stored as JSON, or NULL when nil
-      # @return [Ports::Persistence::Entry] the same `entry`
-      # @raise [Runtime::WiringError] if D1 rejects the insert
       def append(entry)
         @db.execute(
           "INSERT INTO #{quoted_entry_table} (aggregate_id, operation, state, mirrors) VALUES (?, ?, ?, ?)",
-          # `mirrors` (unlike `state`) is a nullable column — an absent
-          # mirrors hash must bind a real SQL NULL, not the four-character
-          # JSON text `"null"` (`JSON.generate(nil)`), or a future `IS NULL`
-          # check against it would never match. Same guard `postgres_era.rb`
-          # already uses for its own journal's `mirrors` column.
+          # Absent mirrors bind SQL NULL, not the JSON text "null" (the column is nullable).
           [entry.id, entry.operation, state_json(entry.state), entry.mirrors && JSON.generate(entry.mirrors)]
         )
         entry
       end
 
-      # Replaces or deletes the aggregate's row for one journal entry.
-      #
-      # @param entry [Ports::Persistence::Entry] the save or delete to materialize
-      # @return [Runtime::Instance, Array] for a save, a new instance over the entry's state;
-      #   for a delete, the `DELETE` statement's empty result rows
-      # @raise [Runtime::WiringError] if D1 rejects the statement
       def project(entry)
         return @db.execute("DELETE FROM #{quoted_table} WHERE id = ?", [entry.id]) if entry.delete?
 
@@ -304,13 +191,7 @@ module Hecks
         instance
       end
 
-      # Reads the whole journal back in append order, for `AppendOnly#recover!` to replay.
-      #
-      # @return [Array<Ports::Persistence::Entry>] every journalled entry, state decoded
-      #   through the state codec and `mirrors` parsed with String keys (nil when none were
-      #   stored); a NULL `operation` reads as `"save"`; `[]` when nothing has been appended
-      # @raise [Runtime::WiringError] if D1 rejects the statement
-      # @raise [JSON::ParserError] if a stored `state` or `mirrors` value is not valid JSON
+      # 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|
           state = JSON.parse(row["state"])
@@ -323,70 +204,25 @@ module Hecks
         end
       end
 
-      # Deletes every row of the aggregate's table and its journal; events and saga rows
-      # are left in place.
-      #
-      # @return [Adapters::D1] self
-      # @raise [Runtime::WiringError] if D1 rejects a statement
+      # 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 and then replaces an instance's current state, as two separate HTTP
-      # requests rather than one batch.
-      #
-      # @param instance [Runtime::Instance] the instance to store
-      # @return [Runtime::Instance] a new instance over a shallow copy of the saved state
-      # @raise [Runtime::WiringError] if D1 rejects either statement; a journal row already
-      #   inserted stays
+      # 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)
         append(entry)
         project(entry)
       end
 
-      # Stores an entry and reports whether it inserted, replaced or conflicted, all in one
-      # batched HTTP request.
-      #
-      # Classification, durable journal append and current-state projection
-      # are one D1 batch transaction and therefore one HTTP request. The first
-      # statement supplies the outcome from database state inside that same
-      # transaction; the runtime performs no preliminary find.
+      # Stores an entry in one D1 batch; returns `:inserted`, `:replaced` or `:conflicted`.
       #
-      # Under `insert_only:`, spending a separate, earlier round trip finding
-      # out whether the row exists before building the batch would be a real
-      # TOCTOU gap (two concurrent creates at the same identity could both
-      # pass that check before either wrote). D1's batch has no conditional
-      # branch of its own, true, but it does not need one: a batch's own
-      # statements already execute in order, atomically, as one transaction
-      # (Connection#batch's own comment) — the exact guarantee the single-
-      # connection adapters' own `@db.transaction do ... end` gets locally.
-      # So the existence check sits inside the batch as its own first
-      # statement, and the two writes are individually gated with `WHERE NOT
-      # EXISTS (...)` against that same table, evaluated in the same
-      # transaction — a row that already existed makes both writes into
-      # real, zero-row no-ops rather than skipping them from the Ruby side,
-      # matching Sqlite#atomic_put's `next` (skip append and project both,
-      # together) with no second HTTP call and no gap for another writer to
-      # land in between the check and the write.
-      #
-      # Three SQL statements, built here and batched together as one
-      # transaction below — see the paragraph above on the real TOCTOU gap
-      # this exact shape closes (the existence check inside the
-      # batch, not run as a separate earlier round trip). Splitting the
-      # per-statement builders out would still need columns/values/slots/
-      # not_exists/quoted_table threaded into each, and would separate
-      # three pieces of one atomic batch across methods with no single
-      # place left to see that they are, together, the fix.
-      #
-      # @param entry [Ports::Persistence::Entry] the save to store
-      # @param insert_only [Boolean] when true, an existing row turns both writes into
-      #   zero-row no-ops
-      # @return [Symbol] `:inserted`, `:replaced`, or `:conflicted` when `insert_only` met an
-      #   existing row and nothing was written
-      # @raise [Runtime::WiringError] if D1 rejects the batch; the whole batch is rolled back
+      # 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)
@@ -405,7 +241,7 @@ module Hecks
               "THEN 'replaced' ELSE 'inserted' END AS status"
           end
 
-        # `mirrors` is nullable (unlike `state`) — see `append`'s own comment.
+        # `mirrors` is nullable; see `append`.
         encoded_mirrors = entry.mirrors && JSON.generate(entry.mirrors)
 
         entry_sql, entry_binds =
@@ -444,12 +280,6 @@ module Hecks
         results.fetch(0).fetch(0).fetch("status").to_sym
       end
 
-      # Journals a delete and then removes the row, whether or not a row exists, as two
-      # separate HTTP requests.
-      #
-      # @param id [String, Object] the aggregate identity, journalled as `id.to_s`
-      # @return [Boolean] always true
-      # @raise [Runtime::WiringError] if D1 rejects either statement
       def delete(id)
         entry = Ports::Persistence::Entry.new(operation: "delete", id: id.to_s, state: nil)
         append(entry)
@@ -457,11 +287,6 @@ module Hecks
         true
       end
 
-      # Inserts an emitted event into the database's shared `events` table.
-      #
-      # @param event [Runtime::Event] the emitted event; `payload` is stored as JSON
-      # @return [Array] the insert's empty result rows; callers ignore it
-      # @raise [Runtime::WiringError] if D1 rejects the insert
       def record_event(event)
         @db.execute(
           "INSERT INTO events (name, aggregate, aggregate_id, payload, occurred_at) VALUES (?, ?, ?, ?, ?)",
@@ -469,12 +294,7 @@ module Hecks
         )
       end
 
-      # Reads back every recorded event in insertion order — the database's whole `events`
-      # table, not only this aggregate's rows.
-      #
-      # @return [Array<Runtime::Event>] the stored events, `payload` parsed with Symbol keys
-      #   and `occurred_at` as stored; `[]` when none are recorded
-      # @raise [Runtime::WiringError] if D1 rejects the statement
+      # 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(
@@ -487,13 +307,24 @@ module Hecks
         end
       end
 
-      # Replaces one saga instance's checkpoint, keyed by domain, process manager and
-      # correlation.
-      #
-      # ── the optional saga-persistence capability (§2) — reuses the DDL
-      # `Sqlite::SchemaBuilder` already shares with Sqlite (`d1.rb`'s own
-      # file header). Same `?`-placeholder shape every other write here
-      # already uses through `Connection#execute`.
+      # 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"]
+          )
+        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
@@ -513,13 +344,6 @@ module Hecks
         )
       end
 
-      # Removes a finished saga instance's checkpoint; a missing row is not an error.
-      #
-      # @param process_manager [String, Symbol] the process manager's name
-      # @param correlation [String, Object] the instance's correlation value, matched as
-      #   `correlation.to_s`
-      # @return [Array] the statement's empty result rows; callers ignore it
-      # @raise [Runtime::WiringError] if D1 rejects the statement
       def delete_saga(process_manager:, correlation:)
         @db.execute(
           "DELETE FROM hecks_saga_instances WHERE domain = ? AND process_manager = ? AND correlation = ?",
@@ -527,18 +351,7 @@ module Hecks
         )
       end
 
-      # Yields every checkpointed saga instance of this adapter's domain, for
-      # `Registry#rehydrate_sagas!` to restore at boot.
-      #
-      # @yieldparam process_manager [String] the process manager's name
-      # @yieldparam correlation [String] the instance's correlation value
-      # @yieldparam state [String] the saga's state name
-      # @yieldparam memory [Hash{Symbol => Object}] the saga's memory, Symbol keys at every depth
-      # @yieldparam completed_compensations [Array] the completed-compensation ledger, `[]`
-      #   when the column is NULL
-      # @return [Enumerator, Array<Hash>] an enumerator over the same five values when no
-      #   block is given; otherwise the raw result rows
-      # @raise [Runtime::WiringError] if D1 rejects the statement
+      # Yields each checkpointed saga of this domain, for `Registry#rehydrate_sagas!`.
       def each_saga
         return enum_for(:each_saga) unless block_given?
 
@@ -555,10 +368,7 @@ module Hecks
 
       private
 
-      # ── SqlQueryBuilder's dialect hooks — identical to Sqlite's, since
-      # D1 speaks the same dialect (copied, not shared by module include,
-      # because Sqlite's own copies are private instance methods on a
-      # different class — see the file header) ───────────────────────
+      # SqlQueryBuilder dialect hooks, copied from Sqlite's private methods.
       def select_list = "*"
       def from_relation = quoted_table
       def dialect_name = "D1"
@@ -585,8 +395,7 @@ module Hecks
         "json_extract(#{quote_ident(name)}, '#{json_path}')"
       end
 
-      # SQLite (and D1, the same engine) has no bare OFFSET — LIMIT -1 is
-      # its own documented unbounded spelling, exactly for this case.
+      # SQLite has no bare OFFSET; LIMIT -1 is its unbounded spelling.
       def unbounded_limit = " LIMIT -1"
 
       def order_clause(order_by, policy)
@@ -597,8 +406,6 @@ module Hecks
         @db.execute(sql, binds).map { |row| Runtime::Instance.new(aggregate: @aggregate, id: row["id"], state: decode(row)) }
       end
 
-      # ── the rest of the dialect ─────────────────────────────────────
-
       def quote_ident(name)
         %("#{name.to_s.gsub('"', '""')}")
       end

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

@@ -2,13 +2,8 @@ require_relative "../../vocabulary"
 
 module Hecks
   module Adapters
-    # The filesystem-backed loader — glob-and-`Kernel.load` a domain's own
-    # `.port`/`.adapter`/`.bluebook`/`.hecksagon`/`.world`/environment-overlay
-    # files off disk, in the order `Vocabulary.fetch("LoadOrder")` requires,
-    # and locate a domain's own root directory by walking up from any file
-    # inside it looking for a `.hecksagon`. What `Hecks.boot(path)` uses when
-    # a caller names a directory rather than an explicit file list (see
-    # `Loader.boot_files` for that other path).
+    # 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
       DOMAIN_ORDER = Hecks::Vocabulary.fetch("LoadOrder")
       PORTS        = "ports".freeze
@@ -41,34 +36,12 @@ module Hecks
         load_each(File.join(root, ADAPTERS), %w[*.adapter */*.adapter */*/*.adapter])
       end
 
-      # Chapters first, judged once, then everything that reads them.
-      # A chapter may be split across files (the language's own grammar is
-      # nine), and judging file one before files two-through-nine exist
-      # refuses references that are perfectly well declared a file later —
-      # see MetaValidator.defer for the whole reasoning. DOMAIN_ORDER
-      # already places every `*.bluebook` ahead of hecksagons and worlds,
-      # so the window ends at the last chapter pattern rather than at a
-      # hand-written list this would otherwise have to keep in step.
+      # 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
+      # judged before its later files exist (see MetaValidator.defer).
       #
-      # `environment:` — one more pair of files, loaded last, not a glob.
-      # Recovered, not new — see Runtime::Loader.boot's own comment for
-      # the provenance. A caller passing `Hecks.boot(path, environment:
-      # "production")` gets exactly `environments/production.hecksagon`
-      # and `environments/production.world` loaded, whichever exist (a
-      # missing one is a silent no-op — not every environment overrides
-      # both; see docs/implemented/guides/wiring.md's "Swapping wiring per
-      # environment" for the motivating case: swapping a driven adapter
-      # — e.g. a real payment gateway for a mock one, or a hosting
-      # layer's tenancy settings — without an `if`/`else` anywhere in
-      # the domain's own wiring). Never matched by `DOMAIN_ORDER`'s own
-      # globs (all non-recursive, none named `environments/*`), so this
-      # is the only thing that ever reaches them. Loaded as genuine
-      # `Hecks.hecksagon "SameDomain" do ... end` / `Hecks.world
-      # "SameDomain" do ... end` blocks — merged into the base file's
-      # own hecksagon/world (Registry#add_hecksagon / #add_world,
-      # concatenate/override rather than replace), so an overlay can
-      # rebind or add settings for anything the base file declared
-      # without needing to know what else the base file said.
+      # An `environment:` overlay (`environments/<name>.hecksagon` and `.world`) loads
+      # last and merges into the base hecksagon/world; a missing overlay file is skipped.
       #
       # @param directory [String] the domain's bluebook directory to load, as
       #   `bluebook_directory` resolves it
@@ -90,12 +63,8 @@ module Hecks
         load_each(directory, [File.join("environments", "#{environment}.world")])
       end
 
-      # Every bluebook in a folder is one declaration set. Individual files
-      # remain organized in the domain expert's language; the folder is the
-      # unit callers load. Builders group declarations by the chapter name in
-      # each file, so a folder may hold more than one chapter without a catalog.
-      # Sorting makes source order deterministic while the deferred window keeps
-      # cross-file references from being judged against a partial chapter.
+      # Loads every bluebook in a folder as one declaration set, judged after all are loaded
+      # so cross-file references never meet a partial chapter.
       #
       # @param directory [String] the directory to glob for bluebook chapter files
       # @param patterns [Array<String>] glob patterns, relative to `directory`, selecting the
@@ -106,23 +75,11 @@ module Hecks
         Bluebook::MetaValidator.judge_deferred!(Hecks.current_registry)
       end
 
-      # The explicit-file sibling of `load_domain` — for a caller that names
-      # its own exact files rather than a directory to glob (`Loader.boot_files`,
-      # behind `Hecks.boot_files`). No `Dir.glob`, no copying: every path here
-      # is a real file on disk, wherever it actually lives, loaded in place —
-      # a `.behaviors` file's `loads` scopes a boot this way specifically so a
-      # per-test boot never has to fake isolation by staging bluebooks into a
-      # tmpdir (see Loader.boot_files's own header for why that pattern is a
-      # hazard, not a convenience).
+      # 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.
       #
-      # Ordered by category, not by the caller's own list order — same four
-      # groups `Vocabulary.fetch("LoadOrder")` walks a directory in
-      # (bluebook chapters, translations, hecksagons, worlds), because a
-      # hecksagon can reference a bluebook's own constants and must not load
-      # first regardless of which order a caller happened to write `loads
-      # "x.hecksagon", "x.bluebook"` in. Bluebook chapters are judged as one
-      # deferred group exactly like `load_domain` does, for the identical
-      # forward-reference reason (MetaValidator.defer's own header).
       # @param files [Array<String>] file paths to load, relative to `bluebook_directory`
       # @param environment [String, nil] the environment name whose overlay, if present,
       #   loads after the selected files
@@ -181,27 +138,11 @@ module Hecks
 
       # Finds the nearest domain directory at or above `from`, or nil if there is not one.
       #
-      # **The domain you are standing in**. Walks up from `from` — the way git
-      # finds `.git` — and answers the nearest directory a boot would accept,
-      # or nil if there is not one above you.
-      #
-      # Marked by a `.hecksagon`, not by a `.bluebook`. Chapters are
-      # everywhere: era translations, the language's own self-hosted grammar,
-      # and `spec/fixtures`, which holds a dozen unrelated ones in a single
-      # directory. A `.hecksagon` is the file that says "this is a domain, and
-      # here is how its aggregates are stored", which is exactly the claim a
-      # caller is relying on when they omit the path.
+      # 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.
       #
-      # Both layouts, because `bluebook_directory` above accepts both: a
-      # domain directory holding a `bluebook/` subdirectory (every example in
-      # this corpus), or one holding the files directly.
-      # Normalised to the outer directory. Standing in `examples/banking/bluebook`,
-      # the `.hecksagon` is right there, so a plain walk stops on the
-      # `bluebook/` directory itself. Both boot identically — `bluebook_directory`
-      # accepts either and `Loader.boot` takes `File.dirname` of what it gets,
-      # so the registry root comes out the same — but `examples/banking` is the
-      # directory a person names, and the one a `.world`'s `dir "data"` reads
-      # as relative to.
+      # A `bluebook/` subdirectory result is normalised to its parent, the directory
+      # a `.world`'s `dir "data"` is relative to.
       #
       # @param from [String] the directory to walk up from; defaults to the process's current
       #   working directory