hecks 1.3.0 → 1.5.0

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

@@ -14,16 +14,26 @@ module Hecks
       PORTS        = "ports".freeze
       ADAPTERS     = "adapters".freeze
 
+      # @param settings [Hash] accepted but not read by this class
+      # @param root [String, nil] accepted but not read by this class
       def initialize(settings: {}, root: nil)
         @settings = settings
         @root     = root
       end
 
+      # Loads the framework's own bundled ports and adapters from `lib/hecks/{ports,adapters}`.
+      #
+      # @return [void]
       def load_library
         load_each(library(PORTS),    %w[*.port])
         load_each(library(ADAPTERS), %w[*/*.adapter */*/*.adapter])
       end
 
+      # Loads a shared root's own ports and adapters, if one was found.
+      #
+      # @param root [String, nil] the shared root directory, as `shared_root` resolves it;
+      #   nil is a no-op
+      # @return [void]
       def load_project(root)
         return unless root
 
@@ -31,7 +41,7 @@ module Hecks
         load_each(File.join(root, ADAPTERS), %w[*.adapter */*.adapter */*/*.adapter])
       end
 
-      # CHAPTERS FIRST, JUDGED ONCE, THEN EVERYTHING THAT READS THEM.
+      # 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 —
@@ -39,8 +49,9 @@ module Hecks
       # 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.
-      # `environment:` — ONE MORE PAIR OF FILES, LOADED LAST, NOT A GLOB.
-      # RECOVERED, not new — see Runtime::Loader.boot's own comment for
+      #
+      # `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
@@ -53,11 +64,17 @@ module Hecks
       # 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
+      # "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.
+      #
+      # @param directory [String] the domain's bluebook directory to load, as
+      #   `bluebook_directory` resolves it
+      # @param environment [String, nil] the environment overlay to load after the domain's
+      #   own files (e.g. `"production"`); nil loads no overlay
+      # @return [void]
       def load_domain(directory, environment: nil)
         boundary = DOMAIN_ORDER.rindex { |pattern| pattern.end_with?(".bluebook") }
         if boundary
@@ -73,18 +90,23 @@ module Hecks
         load_each(directory, [File.join("environments", "#{environment}.world")])
       end
 
-      # EVERY BLUEBOOK IN A FOLDER IS ONE DECLARATION SET. Individual files
+      # 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.
+      #
+      # @param directory [String] the directory to glob for bluebook chapter files
+      # @param patterns [Array<String>] glob patterns, relative to `directory`, selecting the
+      #   chapter files to load
+      # @return [void]
       def load_bluebooks(directory, patterns = ["*.bluebook"])
         Bluebook::MetaValidator.defer { load_each(directory, patterns) }
         Bluebook::MetaValidator.judge_deferred!(Hecks.current_registry)
       end
 
-      # THE EXPLICIT-FILE SIBLING OF `load_domain` — for a caller that names
+      # 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 —
@@ -93,7 +115,7 @@ module Hecks
       # tmpdir (see Loader.boot_files's own header for why that pattern is a
       # hazard, not a convenience).
       #
-      # ORDERED BY CATEGORY, NOT BY THE CALLER'S OWN LIST ORDER — same four
+      # 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
@@ -101,6 +123,10 @@ module Hecks
       # "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
+      # @return [void]
       def load_selected(files, environment: nil)
         bluebooks, rest = files.partition { |f| f.end_with?(".bluebook") }
 
@@ -120,6 +146,14 @@ module Hecks
         load_each(directory, [File.join("environments", "#{environment}.world")])
       end
 
+      # Loads every file under `directory` matching any of `patterns`, in pattern order.
+      #
+      # A no-op if `directory` does not exist.
+      #
+      # @param directory [String] the directory to search
+      # @param patterns [Array<String>] glob patterns, relative to `directory`, of files to
+      #   load with `Kernel.load`
+      # @return [void]
       def load_each(directory, patterns)
         return unless File.directory?(directory)
 
@@ -128,6 +162,13 @@ module Hecks
         end
       end
 
+      # Resolves a domain path to the directory that actually holds its bluebook files.
+      #
+      # @param path [String] a domain directory, holding either a `bluebook/` subdirectory or
+      #   its chapter files directly
+      # @return [String] the `bluebook/` subdirectory's absolute path, if one exists; `path`'s
+      #   own absolute path otherwise
+      # @raise [Errno::ENOENT] if neither directory exists
       def bluebook_directory(path)
         expanded = File.expand_path(path)
         nested   = File.join(expanded, "bluebook")
@@ -138,11 +179,13 @@ module Hecks
         raise Errno::ENOENT, "no such domain directory: #{path}"
       end
 
-      # THE DOMAIN YOU ARE STANDING IN. Walks up from `from` — the way git
+      # 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
+      # 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
@@ -152,13 +195,18 @@ module Hecks
       # 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`,
+      # 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.
+      #
+      # @param from [String] the directory to walk up from; defaults to the process's current
+      #   working directory
+      # @return [String, nil] the resolved domain directory's absolute path, or nil if none is
+      #   found above `from`
       def domain_root(from = Dir.pwd)
         found = nearest_domain(File.expand_path(from))
         return nil unless found
@@ -167,6 +215,12 @@ module Hecks
         File.basename(found) == "bluebook" && domain?(parent) ? parent : found
       end
 
+      # Walks up from `current` until it finds a domain directory, or reaches the filesystem
+      # root.
+      #
+      # @param current [String] the absolute directory path to start searching from
+      # @return [String, nil] the nearest directory (`current` or an ancestor) that `domain?`
+      #   accepts, or nil if none is found before the filesystem root
       def nearest_domain(current)
         loop do
           return current if domain?(current)
@@ -178,11 +232,25 @@ module Hecks
         end
       end
 
+      # Reports whether `directory` is a domain root.
+      #
+      # @param directory [String] the directory to check
+      # @return [Boolean] true if `directory`, or its `bluebook/` subdirectory, holds a
+      #   `.hecksagon` file
       def domain?(directory)
         !Dir[File.join(directory, "*.hecksagon")].empty? ||
           !Dir[File.join(directory, "bluebook", "*.hecksagon")].empty?
       end
 
+      # Resolves the shared root a domain's own ports/adapters overlay from.
+      #
+      # @param given [String, nil] an explicit shared-root override; returned expanded as-is
+      #   when present
+      # @param directory [String] the domain directory to search upward from when `given` is
+      #   nil
+      # @return [String, nil] `given`'s expanded path, or the nearest ancestor of `directory`
+      #   holding a `ports` or `adapters` folder; nil if none is found before the filesystem
+      #   root
       def shared_root(given, directory)
         return File.expand_path(given) if given
 
@@ -198,6 +266,11 @@ module Hecks
         end
       end
 
+      # Resolves the framework's own bundled `folder` directory under `lib/hecks`.
+      #
+      # @param folder [String] `"ports"` or `"adapters"`, the framework's own bundled
+      #   directory name
+      # @return [String] the absolute path to `lib/hecks/<folder>`
       def library(folder)
         File.expand_path("../../#{folder}", __dir__)
       end

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

@@ -4,26 +4,26 @@ require_relative "../../ports/authentication"
 
 module Hecks
   module Adapters
-    # GOOGLE'S OWN OIDC HANDSHAKE — the `authentication` port's one real
-    # implementation today, moved here from being hand-rolled per-app
-    # (an embryonaut_console `google_auth.rb` used to do exactly this;
-    # any hecks-based app gets Google sign-in for free now, the
+    # **Google's own OIDC handshake** — the `authentication` port's one real
+    # implementation today. Consolidates what was hand-rolled per-app
+    # (an embryonaut_console `google_auth.rb` did this on its own) into
+    # one adapter, so any hecks-based app gets Google sign-in for free, the
     # same "one adapter, reusable everywhere" value every other adapter
-    # in this directory already has).
+    # in this directory already has.
     #
-    # `oauth2` does ONLY the authorization-code exchange (no Rack
+    # `oauth2` does only the authorization-code exchange (no Rack
     # middleware, no Omniauth strategy indirection) ; `google-id-token`
-    # does ONLY ID-token verification (signature checked against
+    # does only ID-token verification (signature checked against
     # Google's real, rotating JWKS — real, maintained code, never
     # hand-rolled here). Neither library decides what a verified
-    # (issuer, subject) MEANS — that's `Ports::IdentityResolution`'s
+    # (issuer, subject) means — that's `Ports::IdentityResolution`'s
     # job, called by whoever consumes this port's `verify`.
     #
-    # LAZY REQUIRES, same reasoning `Postgres.connect_for` already
+    # Lazy requires, same reasoning `Postgres.connect_for` already
     # holds itself to for `pg`: a domain that never binds
     # `authentication` to this adapter should never need these gems
-    # installed. This FILE loads in every boot (driven.rb's own
-    # unconditional require_relative list) ; the GEMS load only where
+    # installed. This file loads in every boot (driven.rb's own
+    # unconditional require_relative list) ; the gems load only where
     # a real handshake actually happens.
     #
     # `GOOGLE_CLIENT_ID`/`GOOGLE_CLIENT_SECRET`/`GOOGLE_REDIRECT_URI` —
@@ -34,6 +34,10 @@ module Hecks
 
       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(
@@ -47,6 +51,11 @@ module Hecks
       # The URL to send a browser to, carrying a fresh CSRF `state` the
       # caller is responsible for stashing (a session, typically) and
       # checking 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(
@@ -67,8 +76,20 @@ module Hecks
       # the raw token, never anything a caller would need to re-verify
       # itself. `email_verified` rides along because a caller granting
       # access off this email needs to know Google actually checked it.
+      #
+      # @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 either state is nil or the two
+      #   differ, the code exchange fails, the response has no ID token, or the ID token does
+      #   not verify
+      # @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 GEMS, BEFORE ANYTHING ELSE — not staggered further down
+        # **Both gems, before anything else** — not staggered further down
         # this method: the rescue clause below names GoogleIDToken
         # ::ValidationError, and Ruby resolves that constant reference
         # at the moment an exception is being matched, not at parse

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

@@ -2,26 +2,26 @@ require "time"
 
 module Hecks
   module Adapters
-    # THE `authorization` PORT, FULFILLED BY GOVERNANCE — same registry,
+    # **The `authorization` port, fulfilled by governance** — same registry,
     # same boot, so "ask Governance" is a dispatch against records
     # already sitting in the store this adapter is handed, not a bridge
     # to a second runtime. `Runtime::Dispatcher.new(registry)` is cheap
     # to build fresh per call (`Registry#capability_graph`'s own
     # neighbor, `#repository`, does the same kind of on-demand build) —
     # nothing here holds one across calls, so there is no boot-order
-    # dependency on WHEN Governance's bluebook loads relative to this
+    # dependency on when Governance's bluebook loads relative to this
     # adapter, only that it has by the time `holds_role?` is called.
     #
-    # AN ACTIVE ASSIGNMENT, not merely a historical one : `RoleAssignment`
-    # answers with every assignment an actor has ever held
-    # (`AssignmentsForActor`'s own description — "currently or
-    # historically") and leaves `ends_at` for the caller to read, the
-    # same deferral `Governance::RoleTransition.Allowed` makes for the
-    # same reason. This is that caller.
+    # An active assignment, not merely a past one — `RoleAssignment`
+    # answers with every assignment an actor has ever held, current or
+    # past (`AssignmentsForActor`'s own description covers both), and
+    # leaves `ends_at` for the caller to read, the same deferral
+    # `Governance::RoleTransition.Allowed` makes for the same reason.
+    # This is that caller.
     module GovernanceAuthorization
       module_function
 
-      # `as_of` and `scope` are BOTH optional, same opt-in shape
+      # `as_of` and `scope` are both optional, same opt-in shape
       # `refuse_role_mismatch` already gives `actor_id` itself — an
       # unbound `as_of` skips the `starts_at` check and an unbound
       # `scope` skips the `scope` check, exactly the behavior before
@@ -29,9 +29,21 @@ module Hecks
       # resolved from `Ports::Clock.now`, called by the caller at the
       # door, never by this adapter — see `Ports::Clock`'s own header
       # for why the dispatch path must not consult the clock itself.
+      #
+      # @param registry [Runtime::Registry] the booted registry, to resolve the authorization
+      #   provider's verb
+      # @param actor_id [String] the actor whose grants are checked, compared as a String
+      # @param role [String, Symbol] the role name to look for, compared as a String
+      # @param as_of [Integer, nil] Unix epoch seconds; a grant whose `starts_at` is later, or
+      #   does not parse as a time, does not count. nil skips the `starts_at` check
+      # @param scope [String, nil] the scope the caller acts in; nil skips the scope check
+      # @return [Boolean] true if at least one live grant of `role` to `actor_id` passes the
+      #   `as_of` and `scope` checks
+      # @raise [Runtime::WiringError] if the loaded chapters providing `"authorization"` are
+      #   not exactly one (see `provided_verb`)
       def holds_role?(registry, actor_id:, role:, as_of: nil, scope: nil)
         rows = Runtime::Dispatcher.new(registry).query(
-          "Governance::RoleAssignment.AssignmentsForActor",
+          provided_verb(registry, :assignments),
           actor_id: { value: actor_id.to_s }
         )
 
@@ -43,22 +55,33 @@ module Hecks
         end
       end
 
-      # `scope` UNCHECKED WHEN NOT STATED, same as every other opt-in
+      # `scope` unchecked when not stated, same as every other opt-in
       # field here — a caller that never says which scope it is acting
       # in gets the pre-scope behavior: any live assignment for the role
       # authorizes, everywhere. A caller that does state one only
-      # authorizes against an assignment granted for THAT scope.
+      # authorizes against an assignment granted for that scope.
+      #
+      # @param row [Hash{Symbol => Object}] one `RoleAssignment` row as
+      #   `Runtime::Dispatcher#query` returns it; `:scope` holds a `{value: String}` Hash
+      # @param scope [String, nil] the scope to check against; nil accepts any scope
+      # @return [Boolean] true if `scope` is nil, or the row's own scope matches it
       def in_scope?(row, scope)
         scope.nil? || row[:scope][:value] == scope.to_s
       end
 
-      # `starts_at` IS A FREE-TEXT STRING in the bluebook (`Timestamp`'s
+      # `starts_at` is a free-text string in the bluebook (`Timestamp`'s
       # only invariant is "present", not any particular format) — parsed
       # here with `Time.parse` rather than compared lexically, since
       # nothing guarantees every caller writes it zero-padded ISO 8601.
-      # FAILS CLOSED : a `starts_at` that does not parse is treated as
+      # Fails closed : a `starts_at` that does not parse is treated as
       # not-yet-started rather than silently ignored, the same direction
       # every other check in this method already fails.
+      #
+      # @param row [Hash{Symbol => Object}] one `RoleAssignment` row as
+      #   `Runtime::Dispatcher#query` returns it; `:starts_at` holds a `{value: String}` Hash
+      # @param as_of [Integer, nil] Unix epoch seconds to compare against; nil accepts any row
+      # @return [Boolean] true if `as_of` is nil, or the row's `starts_at` parses and is at or
+      #   before `as_of`; false if `starts_at` does not parse as a time
       def started?(row, as_of)
         return true if as_of.nil?
 
@@ -67,35 +90,81 @@ module Hecks
         false
       end
 
-      # THE OTHER HALF — may role X act as role Y. `RoleTransition.Allowed`
+      # Answers whether one role may act as another.
+      #
+      # **The other half** — may role X act as role Y. `RoleTransition.Allowed`
       # is identified by the exact pair, so at most one row ever comes
       # back ; still read as `.any?` rather than trusting that structurally,
       # the same defensiveness `holds_role?` already has to have anyway
       # since `AssignmentsForActor` can return several.
+      #
+      # @param registry [Runtime::Registry] the booted registry, to resolve the authorization
+      #   provider's verb
+      # @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 (not ended) allowance lets `from_role` act as
+      #   `to_role`
+      # @raise [Runtime::WiringError] if the loaded chapters providing `"authorization"` are
+      #   not exactly one (see `provided_verb`)
       def authorized_as?(registry, from_role:, to_role:)
         rows = Runtime::Dispatcher.new(registry).query(
-          "Governance::RoleTransition.Allowed",
+          provided_verb(registry, :transitions),
           from_role: { value: from_role.to_s }, to_role: { value: to_role.to_s }
         )
 
         rows.any? { |row| row[:ends_at].nil? }
       end
 
-      # THE ROLE ITSELF, not just a yes/no about one — the same
+      # The role itself, not just a yes/no about one — the same
       # `AssignmentsForActor` query `holds_role?` runs, just returning
       # the live (non-revoked) row's `role_name` instead of comparing it
       # against a caller-supplied guess. `nil` for no live assignment at
       # all — the caller's own fallback (an aggregate's own role field,
       # a default) is domain-specific and does not belong here.
+      #
+      # @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
+      #   not exactly one (see `provided_verb`)
       def live_role_for(registry, actor_id:)
         rows = Runtime::Dispatcher.new(registry).query(
-          "Governance::RoleAssignment.AssignmentsForActor",
+          provided_verb(registry, :assignments),
           actor_id: { value: actor_id.to_s }
         )
 
         live = rows.find { |row| row[:ends_at].nil? }
         live && live[:role_name][:value]
       end
+
+      # The verb, read from the provider's own declaration — `provides
+      # "authorization", assignments: ..., transitions: ...` on whichever
+      # loaded chapter declares it (Governance's, in every boot today).
+      # Exactly one provider, the same "the runtime will not choose for
+      # you" rule `Ports::Authorization.adapter` applies to adapters.
+      #
+      # @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
+      #   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.map(&:name).sort.join(', ')})" unless providers.empty?} — " \
+                "a role lookup needs exactly one (framework members declaring it: " \
+                "#{Framework.providers_of(Bluebook::Capabilities::AUTHORIZATION).join(', ')})"
+        end
+
+        providers.first.provided_verb(Bluebook::Capabilities::AUTHORIZATION, key)
+      end
     end
   end
 end

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

@@ -6,18 +6,23 @@ module Hecks
       # The append-only journal beside the snapshot: one JSON line per
       # entry, fsynced on append, replayed over the snapshot on read.
       module Journal
+        # 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; `[]` when the journal file does not exist or is empty
+        # @raise [Malformed] if a journal line is not valid JSON
         def entries
           return [] unless File.exist?(@journal_path)
 
           File.readlines(@journal_path, chomp: true).reject(&:empty?).map do |line|
             value = JSON.parse(line)
-            state = value["state"]&.transform_keys(&:to_sym)
+            state = Ports::Persistence::StateCodec.decode(@aggregate, value["state"])
             Ports::Persistence::Entry.new(operation: value.fetch("operation"), id: value.fetch("id"), state: state,
                                           mirrors: value["mirrors"])
           end
         end
 
-        # An EXPLICIT, opt-in maintenance operation — never run
+        # An explicit, opt-in maintenance operation — never run
         # automatically after an ordinary save/delete. Heki's journal is
         # not a disposable write-ahead log: it is this adapter's own
         # answer to `entries`, and `entries` is a real port contract
@@ -26,7 +31,7 @@ module Hecks
         # and `Registry#projection_current?` to catch a projection up to
         # its authoritative source, and by `bin/history` to show "every
         # journal entry a domain's append-only adapters hold" — the same
-        # contract Postgres/Sqlite/D1 uphold by way of a journal TABLE
+        # contract Postgres/Sqlite/D1 uphold by way of a journal table
         # that is never pruned. A real example (`examples/banking`,
         # `persisted_by("Heki")` + `projected_by("SqliteProjection")`)
         # depends on this today. Compacting throws that full history away
@@ -46,6 +51,9 @@ module Hecks
         # once. A crash before `write` completes leaves the journal
         # fully intact and the prior snapshot untouched, exactly today's
         # existing crash-recovery guarantee.
+        #
+        # @return [void]
+        # @raise [Malformed] if the snapshot or journal file is corrupt
         def compact!
           with_lock do
             current = replay_journal(read_snapshot)
@@ -95,7 +103,8 @@ module Hecks
         end
 
         def append_entry(operation, id, state)
-          line = "#{JSON.generate(operation: operation, id: id.to_s, state: state, mirrors: @entry_mirrors)}\n"
+          encoded = Ports::Persistence::StateCodec.encode(@aggregate, state)
+          line = "#{JSON.generate(operation: operation, id: id.to_s, state: encoded, mirrors: @entry_mirrors)}\n"
 
           # One write, not JSON-then-newline as two: two concurrent
           # appends can only interleave *between* writes, never inside

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

@@ -4,31 +4,41 @@ require_relative "journal"
 module Hecks
   module Adapters
     class Heki
-      # THE OPTIONAL saga-persistence capability (§2), Heki's own shape —
-      # a SIBLING snapshot+journal file pair, built the exact same way an
-      # aggregate's own persistence already is: `Snapshot`/`Journal`
-      # (heki/snapshot.rb, heki/journal.rb) operate generically on
-      # `@path`/`@journal_path`/`@entry_mirrors` and never touch
-      # `@aggregate`, so this reuses them unchanged rather than
-      # re-deriving the same binary framing and crash-recovery replay.
+      # The optional saga-persistence capability (§2)'s Heki-specific store — a sibling
+      # snapshot+journal file pair, keyed by (domain, process manager, correlation).
+      #
+      # ## Why a sibling file pair, not a table
+      #
+      # Built the exact same way an aggregate's own persistence already
+      # is: `Snapshot`/`Journal` (heki/snapshot.rb, heki/journal.rb)
+      # operate generically on `@path`/`@journal_path`/`@entry_mirrors`
+      # and never touch `@aggregate`, so this reuses them unchanged
+      # rather than re-deriving the same binary framing and
+      # crash-recovery replay.
+      #
+      # ## Where the file lives
       #
       # Reserved file name (`hecks_saga_instances.heki`, matching the
       # `hecks_`-prefix convention every other new saga table in this
       # work uses) avoids colliding with any real aggregate's own
-      # `storage_name`. Lives in the SAME directory an aggregate's own
+      # `storage_name`. Lives in the same directory an aggregate's own
       # `.heki` file would (`File.dirname(@path)`, `Heki`'s own call
       # below) — which, since Heki's `resolve_path` has no per-domain
-      # component at all, is typically shared across EVERY domain
+      # component at all, is typically shared across every domain
       # booted from the same `root`. `domain` is therefore carried
       # inside each record and filtered on read, the same reason
       # Postgres's own `hecks_saga_instances` keeps an explicit `domain`
       # column under schema isolation (§3).
       #
-      # ONE flat records hash, keyed by a composite string (Heki's own
+      # ## Record shape
+      #
+      # One flat records hash, keyed by a composite string (Heki's own
       # snapshot format is id-keyed, not tuple-keyed) — never exposed
       # outside this class; `each_saga` yields the five real fields a
       # caller actually wants, not the internal key shape.
       #
+      # ## Locking
+      #
       # Locked the same way an aggregate's own store is: `with_lock`
       # (`Snapshot`, shared) serializes each save/delete's read-modify-
       # write against `@path`'s own lock file — a saga gets exactly the
@@ -38,12 +48,27 @@ module Hecks
         include Snapshot
         include Journal
 
+        # @param dir [String] the directory to hold the saga snapshot+journal file pair,
+        #   shared with the aggregate `.heki` files that already live there
         def initialize(dir)
           @path         = File.join(dir, "hecks_saga_instances.heki")
           @journal_path = "#{@path}.journal"
           @entry_mirrors = nil
         end
 
+        # Upserts one saga instance's checkpoint, keyed by domain, process manager and
+        # correlation, under the file lock.
+        #
+        # @param domain [String] the owning domain, carried in the record and filtered on
+        #   read
+        # @param process_manager [String] the process manager's name
+        # @param correlation [String] the instance's correlation value
+        # @param state [String] the saga's current state name
+        # @param memory [Hash] the saga's working memory to persist
+        # @param completed_compensations [Array] the ledger of completed compensable legs;
+        #   `[]` when none
+        # @return [Hash{String => Hash}] the store's full internal records Hash after the
+        #   write; callers ignore it
         def save_saga(domain, process_manager, correlation, state, memory, completed_compensations = [])
           key    = key_for(domain, process_manager, correlation)
           record = { "domain" => domain, "process_manager" => process_manager,
@@ -59,6 +84,14 @@ module Hecks
           end
         end
 
+        # Removes a finished saga instance's checkpoint, if present, under the file lock; a
+        # missing one is not an error.
+        #
+        # @param domain [String] the owning domain
+        # @param process_manager [String] the process manager's name
+        # @param correlation [String] the instance's correlation value
+        # @return [Hash{String => Hash}] the store's full internal records Hash after the
+        #   delete; callers ignore it
         def delete_saga(domain, process_manager, correlation)
           key = key_for(domain, process_manager, correlation)
 
@@ -71,6 +104,19 @@ module Hecks
           end
         end
 
+        # Yields every checkpointed saga instance of `domain`, for `Registry
+        # #rehydrate_sagas!` to restore at boot.
+        #
+        # @param domain [String] the owning domain to filter records to
+        # @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 record carries none
+        # @return [Enumerator, Hash{String => Hash}] an enumerator over the same five values
+        #   when no block is given; otherwise the store's full internal records Hash
         def each_saga(domain)
           return enum_for(:each_saga, domain) unless block_given?