hecks 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: badbf552a5137cc39f791c4a398fe7d33423ff6d15c82cb018d1ef7c464af754
-  data.tar.gz: 5bf8d933f52178d2870d19dd0e33b03cacd060b848b54340c4940edbe94e008e
+  metadata.gz: 830e92d9660dc86cc7de1af49d85fd7ce5ab611e07341dd11f4633274b920fda
+  data.tar.gz: 1c70b3c2994fd520a604ebd8c8cc8a53e7531e3cb5ba1dd59c6fd751b9b9dd99
 SHA512:
-  metadata.gz: 9327ee7366dacb9dcc90fc155999e5ff055efefc8e840ff4ddb08a7042adfcedbe5396c7547713562bebe1db618017b6851421f48d0ac300ab4339cf674a4cca
-  data.tar.gz: 97e1aa8115377269a23b29609e88370f86cfaec8dee9f79889232755dea7a55921d7e3db2fa6c3af26ca4f2afaca56a034fd7a6b5b8413ad00e45aef9c24c0d9
+  metadata.gz: 3aeb0240903bed58fbd5684c23ee2069e9b3021aef07082d11e26ffa5052cebccf42d78e3aff243ba192183460056113e0510c7667306d1ed2cde3048ad118c0
+  data.tar.gz: e104c2252f0dbbb1ba5ea97a0f6f56f890cab76e12ff86f246605003738228b94062e317f16db1ebfb376753536d8309cedff86e00275781497232de67b17e1e

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

@@ -40,10 +40,22 @@ module Hecks
 
       module_function
 
+      # Asks the model for the next best interview question, as a raw parsed-JSON reply.
+      #
       # **The next best question**. `state` is whatever
       # `Interview::Session#declaration`/`#gaps` produced — passed
       # through as JSON, not reformatted, so this adapter never
       # re-derives what the session already knows.
+      #
+      # @param state [Hash] the interview's whole current picture (declaration plus gaps),
+      #   JSON-able
+      # @param asked [Array<Object>] JSON-able record of the questions already asked
+      # @return [Object] the parsed JSON reply, expected to be a Hash holding a `"questions"`
+      #   array; shape validated downstream by `Ports::Agent::Answers.questions`
+      # @raise [Ports::Agent::Unavailable] if the `claude` binary is missing, the subprocess
+      #   fails, or the call times out
+      # @raise [Ports::Agent::ValidationError] if the CLI's own envelope has no `"result"`, or
+      #   the result text is not valid JSON
       def ask(state:, asked:)
         call(
           system:  SYSTEM_PREFIX + "Given the domain model so far, ask the single best next " \
@@ -53,7 +65,18 @@ module Hecks
         )
       end
 
+      # Turns a human's sentence into proposed declarations, as a raw parsed-JSON reply.
+      #
       # Prose -> proposed declarations.
+      #
+      # @param prose [String] a human's plain-English sentence
+      # @param state [Hash] the interview's whole current picture, JSON-able
+      # @return [Object] the parsed JSON reply, expected to be a Hash holding a `"proposals"`
+      #   array; shape validated downstream by `Ports::Agent::Answers.proposals`
+      # @raise [Ports::Agent::Unavailable] if the `claude` binary is missing, the subprocess
+      #   fails, or the call times out
+      # @raise [Ports::Agent::ValidationError] if the CLI's own envelope has no `"result"`, or
+      #   the result text is not valid JSON
       def interpret(prose:, state:)
         call(
           system:  SYSTEM_PREFIX + "Given the domain model so far and a sentence the human just said, " \
@@ -66,10 +89,22 @@ module Hecks
         )
       end
 
+      # Asks the model to judge a declared model on taste, as a raw parsed-JSON reply.
+      #
       # What is wrong with this as a model — closed to the same kind
       # vocabulary `Ports::Agent::CRITIQUE_KINDS` declares, spelled out
       # here too since the system prompt is the only place the model
       # itself ever sees that list.
+      #
+      # @param declared [Hash] the chapter as declared so far, JSON-able
+      # @param refusals [Array<Object>] JSON-able refusals the language itself already raised
+      # @param findings [Array<Object>] JSON-able mechanical findings already found
+      # @return [Object] the parsed JSON reply, expected to be a Hash holding a `"findings"`
+      #   array; shape validated downstream by `Ports::Agent::Answers.findings`
+      # @raise [Ports::Agent::Unavailable] if the `claude` binary is missing, the subprocess
+      #   fails, or the call times out
+      # @raise [Ports::Agent::ValidationError] if the CLI's own envelope has no `"result"`, or
+      #   the result text is not valid JSON
       def critique(declared:, refusals:, findings:)
         kinds = Ports::Agent::CRITIQUE_KINDS.join(", ")
         call(
@@ -82,9 +117,22 @@ module Hecks
         )
       end
 
+      # Suggests a name for a construct, as a raw parsed-JSON reply.
+      #
       # **Vocabulary help**. Named `suggest_name`, not `name` — see
       # `Ports::Agent#suggest_name`'s own comment for why `name` is
       # never a safe module-function name here.
+      #
+      # @param meaning [String] what the new name needs to mean
+      # @param kind [String] the kind of construct being named, such as `"event"`
+      # @param near [Array<String>] names already in use nearby, which a suggestion must not
+      #   collide with
+      # @return [Object] the parsed JSON reply, expected to be a Hash holding a `"names"`
+      #   array; shape validated downstream by `Ports::Agent::Answers.suggestions`
+      # @raise [Ports::Agent::Unavailable] if the `claude` binary is missing, the subprocess
+      #   fails, or the call times out
+      # @raise [Ports::Agent::ValidationError] if the CLI's own envelope has no `"result"`, or
+      #   the result text is not valid JSON
       def suggest_name(meaning:, kind:, near:)
         call(
           system:  SYSTEM_PREFIX + "Suggest a name for a #{kind} meaning \"#{meaning}\", distinct from " \
@@ -96,6 +144,16 @@ module Hecks
 
       # ── transport ───────────────────────────────────────────────────
 
+      # Runs `claude` as a subprocess with `payload` on stdin and returns its parsed JSON reply.
+      #
+      # @param system [String] the system-prompt text appended via `--append-system-prompt`
+      # @param payload [Hash] the JSON-able payload written to the subprocess's stdin
+      # @return [Object] the parsed JSON value nested under the CLI envelope's `"result"` key
+      #   (see `unwrap`)
+      # @raise [Ports::Agent::Unavailable] if the `claude` binary is missing, the subprocess
+      #   exits non-zero, or the call does not finish within `TIMEOUT_SECONDS`
+      # @raise [Ports::Agent::ValidationError] if the envelope has no `"result"`, or the
+      #   result text is not valid JSON (see `unwrap`)
       def call(system:, payload:)
         stdout, status = Timeout.timeout(TIMEOUT_SECONDS) do
           Open3.capture2(
@@ -113,6 +171,13 @@ module Hecks
         raise Ports::Agent::Unavailable, "claude is not on PATH: #{e.message}"
       end
 
+      # Unwraps the CLI's own JSON envelope down to the model's parsed reply.
+      #
+      # @param stdout [String] the raw stdout of the `claude` CLI invocation, the outer
+      #   `{"result": "..."}` envelope
+      # @return [Object] the JSON value parsed out of the envelope's `"result"` string
+      # @raise [Ports::Agent::ValidationError] if the envelope has no `"result"` key, or
+      #   `result` is not valid JSON
       def unwrap(stdout)
         envelope = JSON.parse(stdout)
         result = envelope["result"]

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
 
@@ -39,6 +49,7 @@ 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
       # the provenance. A caller passing `Hecks.boot(path, environment:
@@ -58,6 +69,12 @@ module Hecks
       # 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
@@ -79,6 +96,11 @@ module Hecks
       # 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)
@@ -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,6 +179,8 @@ module Hecks
         raise Errno::ENOENT, "no such domain directory: #{path}"
       end
 
+      # 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.
@@ -159,6 +202,11 @@ module Hecks
       # 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

@@ -5,11 +5,11 @@ 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
+    # 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
     # middleware, no Omniauth strategy indirection) ; `google-id-token`
@@ -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,6 +76,18 @@ 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
         # this method: the rescue clause below names GoogleIDToken

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

@@ -12,12 +12,12 @@ module Hecks
     # 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
 
@@ -29,6 +29,18 @@ 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(
           provided_verb(registry, :assignments),
@@ -48,6 +60,11 @@ module Hecks
       # 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.
+      #
+      # @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
@@ -59,6 +76,12 @@ module Hecks
       # 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,11 +90,23 @@ module Hecks
         false
       end
 
+      # 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(
           provided_verb(registry, :transitions),
@@ -87,6 +122,14 @@ module Hecks
       # 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(
           provided_verb(registry, :assignments),
@@ -102,6 +145,14 @@ module Hecks
       # 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

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

@@ -6,6 +6,11 @@ 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)
 
@@ -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)

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

@@ -4,13 +4,19 @@ 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
@@ -24,11 +30,15 @@ module Hecks
       # Postgres's own `hecks_saga_instances` keeps an explicit `domain`
       # column under schema isolation (§3).
       #
+      # ## 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?
 

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

@@ -23,7 +23,7 @@ module Hecks
           raise Malformed, "#{@path}: json error: #{e.message}"
         end
 
-        # Temp-file-plus-rename, fsynced before the rename: a reader can
+        # Temp-file-plus-rename, fsynced ahead of the `File.rename` call: a reader can
         # only ever see the last complete snapshot or the one before it,
         # never a truncated or partial one — `File.binwrite`'s old
         # truncate-then-write left a window, proportional to the whole