hecks 2.7.0 → 2.9.0

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

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

@@ -4,31 +4,14 @@ require_relative "../../ports/authentication"
 
 module Hecks
   module Adapters
-    # **Google's own OIDC handshake** — the `authentication` port's one real
-    # implementation today. Consolidates what was hand-rolled per-app
-    # (a console app's `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.
+    # Google's OIDC handshake — the `authentication` port's adapter for Google
+    # sign-in, via `oauth2` (code exchange) and `google-id-token` (verification).
     #
-    # `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
-    # 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
-    # job, called by whoever consumes this port's `verify`.
+    # `oauth2`/`google-id-token` load lazily, inside the methods that use
+    # them, so a domain that never binds this adapter never needs them installed.
     #
-    # 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
-    # a real handshake actually happens.
-    #
-    # `GOOGLE_CLIENT_ID`/`GOOGLE_CLIENT_SECRET`/`GOOGLE_REDIRECT_URI` —
-    # no defaults, on purpose: a login mechanism silently
-    # half-configured is worse than one that refuses to boot at all.
+    # `GOOGLE_CLIENT_ID`/`GOOGLE_CLIENT_SECRET`/`GOOGLE_REDIRECT_URI` have no
+    # defaults, on purpose: a half-configured login should refuse to boot.
     module GoogleAuthentication
       ISSUER = "https://accounts.google.com".freeze
 
@@ -48,9 +31,8 @@ module Hecks
         )
       end
 
-      # 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`.
+      # The URL to send a browser to, carrying a fresh CSRF `state` the caller
+      # must stash (typically in a session) and check again in `verify`.
       #
       # @return [Array(String, String)] the URL to send the browser to, and the fresh CSRF
       #   `state` embedded in it
@@ -66,38 +48,22 @@ module Hecks
         [url, state]
       end
 
-      # Exchanges `code` for tokens, verifies the returned ID token's
-      # signature and claims against Google's own JWKS, and confirms
-      # `state` matches what `authorization_url` handed out — a
-      # mismatch (or any failure in the exchange/verification itself)
-      # is a Ports::Authentication::ValidationError, never a
-      # silently-empty result. Returns
-      # {issuer:, subject:, email:, email_verified:} on success — never
-      # 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.
-      #
+      # Exchanges `code` for tokens and verifies the ID token against Google's
+      # JWKS; `email_verified` tells a caller if Google actually checked the email.
       # @param code [String] the authorization code the provider sent back
       # @param state [String, nil] the state parameter the provider returned; nil is refused
       # @param expected_state [String, nil] the state `authorization_url` handed out before
       #   the redirect; nil is refused
       # @return [Hash{Symbol => Object}] `issuer:` and `subject:` (String), `email:` (String,
       #   or nil if the token carries none), `email_verified:` (Boolean)
-      # @raise [Ports::Authentication::ValidationError] if 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 [Ports::Authentication::ValidationError] if the state check, code exchange, or
+      #   ID token verification fails
       # @raise [KeyError] if `GOOGLE_CLIENT_ID` or `GOOGLE_REDIRECT_URI` is unset, or a
       #   verified token lacks an `iss` or `sub` claim
       def verify(code:, state:, expected_state:)
-        # **Both 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
-        # time. An OAuth2::Error raised before a later `require
-        # "google-id-token"` line ran would make the rescue clause
-        # itself blow up on an undefined constant, masking the real
-        # error. Requiring both up front means whichever one raises
-        # first, the constant is already there to catch it.
+        # Both requires happen up front: the rescue below matches
+        # GoogleIDToken::ValidationError, resolved only when caught, so
+        # requiring it lazily after an OAuth2::Error would mask the real failure.
         require "oauth2"
         require "google-id-token"
 

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

@@ -2,45 +2,23 @@ require "time"
 
 module Hecks
   module Adapters
-    # **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
-    # adapter, only that it has by the time `holds_role?` is called.
-    #
-    # 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.
+    # The `authorization` port, answered by dispatching queries against Governance's records
+    # in the same registry. Only assignments with no `ends_at` count as live.
     module GovernanceAuthorization
       module_function
 
-      # `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
-      # either existed. Neither is fetched here: `as_of` arrives already
-      # 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.
+      # Reports whether `actor_id` holds a live grant of `role`.
       #
-      # @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
+      # `as_of` and `scope` are opt-in: nil skips the matching check. `as_of` comes from the
+      # caller, since the dispatch path must not read the clock (see `Ports::Clock`).
+      #
+      # @param registry [Runtime::Registry] the booted registry
+      # @param actor_id [String] the actor whose grants are checked
+      # @param role [String, Symbol] the role name to look for
+      # @param as_of [Integer, nil] Unix epoch seconds; a later (or unparseable) `starts_at` fails
       # @param scope [String, nil] the scope the caller acts in; nil skips the scope check
-      # @return [Boolean] true if 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`)
+      # @return [Boolean] true if a live grant of `role` to `actor_id` passes both checks
+      # @raise [Runtime::WiringError] unless exactly one chapter provides `"authorization"`
       def holds_role?(registry, actor_id:, role:, as_of: nil, scope: nil)
         rows = Runtime::Dispatcher.new(registry).query(
           provided_verb(registry, :assignments),
@@ -55,11 +33,7 @@ module Hecks
         end
       end
 
-      # `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.
+      # Without a `scope`, any live assignment for the role authorizes everywhere.
       #
       # @param row [Hash{Symbol => Object}] one `RoleAssignment` row as
       #   `Runtime::Dispatcher#query` returns it; `:scope` holds a `{value: String}` Hash
@@ -69,13 +43,8 @@ module Hecks
         scope.nil? || row[:scope][:value] == scope.to_s
       end
 
-      # `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
-      # not-yet-started rather than silently ignored, the same direction
-      # every other check in this method already fails.
+      # `starts_at` is free text, so it is parsed with `Time.parse` rather than compared
+      # lexically. Fails closed: an unparseable value counts as not yet started.
       #
       # @param row [Hash{Symbol => Object}] one `RoleAssignment` row as
       #   `Runtime::Dispatcher#query` returns it; `:starts_at` holds a `{value: String}` Hash
@@ -92,21 +61,13 @@ module Hecks
 
       # 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.
+      # Read with `.any?` rather than trusting that the exact-pair lookup returns one row.
       #
-      # @param registry [Runtime::Registry] the booted registry, to resolve the authorization
-      #   provider's verb
+      # @param registry [Runtime::Registry] the booted registry
       # @param from_role [String, Symbol] the role the caller holds, compared as a String
-      # @param to_role [String, Symbol] the role the caller wants to act as, compared as a
-      #   String
-      # @return [Boolean] true if a live (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`)
+      # @param to_role [String, Symbol] the role the caller wants to act as, compared as a String
+      # @return [Boolean] true if a live allowance lets `from_role` act as `to_role`
+      # @raise [Runtime::WiringError] unless exactly one chapter provides `"authorization"`
       def authorized_as?(registry, from_role:, to_role:)
         rows = Runtime::Dispatcher.new(registry).query(
           provided_verb(registry, :transitions),
@@ -116,12 +77,7 @@ module Hecks
         rows.any? { |row| row[:ends_at].nil? }
       end
 
-      # 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.
+      # Returns the actor's live role name, or nil; any fallback is the caller's.
       #
       # @param registry [Runtime::Registry] the booted registry, to resolve the authorization
       #   provider's verb
@@ -140,11 +96,8 @@ module Hecks
         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.
+      # Reads a verb from the one chapter that `provides "authorization"`; the runtime will
+      # not choose between several (as in `Ports::Authorization.adapter`).
       #
       # @param registry [Runtime::Registry] the booted registry to search for the
       #   `"authorization"` provider

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

@@ -22,35 +22,13 @@ module Hecks
           end
         end
 
-        # 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
-        # (`Ports::Persistence::AppendOnly`'s own required-methods list)
-        # read in full, forever, by `Ports::Projection::Worker#catch_up!`
-        # 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
-        # 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
-        # for whatever happened before the call — correct only for an
-        # aggregate nothing ever projects from; callers (`bin/
-        # heki_compact`) are responsible for confirming that first.
+        # Folds the journal into the snapshot and truncates it. Opt-in; never run after a save.
         #
-        # Crash-safety ordering: `write` below is the exact same
-        # temp-file, fsync, atomic-rename sequence `save`/`delete`
-        # already use — the snapshot it produces is confirmed durably on
-        # disk before this method ever touches the journal. Only once
-        # that succeeds does `truncate_journal!` run. A crash between the
-        # two leaves old (now fully redundant) journal lines in place;
-        # replaying them again over the fresh snapshot on the next boot
-        # is idempotent — the same value gets set again, never a wrong
-        # one — so nothing is lost, just a little wasted replay work
-        # once. A crash before `write` completes leaves the journal
-        # fully intact and the prior snapshot untouched, exactly today's
-        # existing crash-recovery guarantee.
+        # This discards the history `entries` returns, which projections and `bin/history`
+        # read in full, so use it only on an aggregate nothing projects from.
+        #
+        # The snapshot is written durably before the journal is truncated; a crash between
+        # the two leaves redundant lines whose replay is idempotent.
         #
         # @return [void]
         # @raise [Malformed] if the snapshot or journal file is corrupt
@@ -68,15 +46,7 @@ module Hecks
         def truncate_journal!
           return unless File.exist?(@journal_path)
 
-          # A single `truncate(0)` syscall on an already-open file
-          # descriptor — the file's length changes atomically at the
-          # filesystem level, so there is no "half truncated" state to
-          # observe even under a crash mid-call. `fsync` below makes
-          # that change durable before this method returns; without it
-          # a crash could still leave the old (harmless-to-replay)
-          # content on disk after a normal return, which is fine per
-          # the crash-safety note above, but the durable case is the
-          # one actually worth returning success for.
+          # `truncate(0)` is atomic; the fsync makes it durable before returning.
           File.open(@journal_path, "r+b") do |file|
             file.truncate(0)
             file.flush
@@ -106,10 +76,7 @@ module Hecks
           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
-          # one, so this line can't come out split by another process's
-          # line landing in the middle of it.
+          # One write, so a concurrent append cannot land in the middle of this line.
           File.open(@journal_path, "ab") do |journal|
             journal.write(line)
             journal.flush

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

@@ -4,46 +4,11 @@ require_relative "journal"
 module Hecks
   module Adapters
     class Heki
-      # The optional saga-persistence capability (§2)'s Heki-specific store — a sibling
-      # snapshot+journal file pair, keyed by (domain, process manager, correlation).
+      # Saga checkpoints in 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
-      # `.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
-      # 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).
-      #
-      # ## 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
-      # durability and concurrency-safety this adapter already gives its
-      # aggregates, no better, no worse.
+      # The file is shared by every domain booted from the same directory, so `domain`
+      # is stored in each record and filtered on read.
       class SagaStore
         include Snapshot
         include Journal
@@ -59,16 +24,13 @@ module Hecks
         # 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 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
+        # @param completed_compensations [Array] completed compensable legs; `[]` when none
+        # @return [Hash{String => Hash}] the full 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,
@@ -104,8 +66,7 @@ module Hecks
           end
         end
 
-        # Yields every checkpointed saga instance of `domain`, for `Registry
-        # #rehydrate_sagas!` to restore at boot.
+        # Yields every checkpointed saga instance of `domain`, for boot-time rehydration.
         #
         # @param domain [String] the owning domain to filter records to
         # @yieldparam process_manager [String] the process manager's name
@@ -113,10 +74,8 @@ module Hecks
         # @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
+        # @yieldparam completed_compensations [Array] the completed-compensation ledger
+        # @return [Enumerator, Hash{String => Hash}] an enumerator when no block is given
         def each_saga(domain)
           return enum_for(:each_saga, domain) unless block_given?
 
@@ -135,9 +94,8 @@ module Hecks
           @store ||= replay_journal(read_snapshot)
         end
 
-        # A plain space-joined key, not anything fancier — a correlation value is real
-        # business data (an order id, a customer reference) and nothing
-        # here should assume it never contains a space.
+        # Space-joined; the key is opaque and never parsed back, so spaces in a
+        # correlation value are harmless.
         def key_for(domain, process_manager, correlation) = [domain, process_manager, correlation].join(" ")
       end
     end

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

@@ -23,11 +23,7 @@ module Hecks
           raise Malformed, "#{@path}: json error: #{e.message}"
         end
 
-        # 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
-        # dataset, where the file on disk was neither.
+        # Temp file, fsync, then rename, so a reader never sees a partial snapshot.
         def write(records)
           sorted = records.sort_by { |id, _| id }.to_h
           json   = JSON.generate(sorted)
@@ -42,13 +38,9 @@ module Hecks
           File.rename(tmp, @path)
         end
 
-        # Serializes the read-modify-write each save/delete does against
-        # the snapshot (and the journal append that precedes it) across
-        # processes — `flock` is per-process advisory, so every writer
-        # has to go through this to matter, which `with_lock`'s only two
-        # callers (`Heki#save`/`#delete`, `SagaStore#save_saga`/
-        # `#delete_saga`) both do. The lock file is separate from
-        # `@path` so a held lock never blocks `write`'s own rename.
+        # Serializes each save/delete's read-modify-write across processes; `flock` is
+        # advisory, so every writer must use it. The lock file is separate from `@path`
+        # so a held lock never blocks `write`'s rename.
         def with_lock
           File.open(lock_path, File::CREAT | File::RDWR, 0o644) do |lock|
             lock.flock(File::LOCK_EX)