hecks 2.8.0 → 3.0.0

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 `hecks 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)

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

@@ -35,12 +35,9 @@ module Hecks
         @aggregate = aggregate
         @path      = resolve_path(settings, root)
         @journal_path = "#{@path}.journal"
-        @events    = []
-        # The optional saga-persistence capability's own scoping (§2/§4)
-        # — falls back to the aggregate's own name for a directly-
-        # instantiated adapter (specs), same fallback shape Postgres's
-        # own @domain already uses.
-        @domain    = (
+        @events = []
+        # Saga scope; falls back to the aggregate's name for a directly built adapter.
+        @domain = (
           if settings.key?(:domain)
             settings[:domain]
           elsif settings.key?("domain")
@@ -81,13 +78,7 @@ module Hecks
 
       # Answers a declared query specification against the projected records.
       #
-      # `registry: context[:registry]` — Memory's own `query` already
-      # threads this through; Heki's own never did, which made
-      # `none_in_state?` (Ports::Query::InMemory) unconditionally
-      # return `true` (its own graceful "no registry, no way to look
-      # the target up" default) for every `none_in_state` where-clause
-      # against a Heki-backed aggregate — silently excluding nothing,
-      # always, no matter the actual target state.
+      # The registry is passed through so `none_in_state` clauses can look up their target.
       #
       # @param specification [QuerySpecification::Common::Options,
       #   Bluebook::Behaviour::ReadModel::FilteredOptions] the declared query specification
@@ -113,17 +104,11 @@ module Hecks
 
       # Applies one journaled entry to the current-state snapshot.
       #
-      # Reads fresh rather than trusting the memoized `store` — under
-      # `with_lock`, another process may have projected a snapshot since
-      # this one last read it, and mutating *its* stale copy would
-      # overwrite that write on disk rather than layer on top of it.
+      # Reads fresh, not the memoized `store`: another process may have projected since,
+      # and a stale copy would overwrite that write.
       #
-      # On a delete, though, the record `current.delete` finds is already
-      # gone: every caller (`#delete` above, `AppendOnly#delete`) appends
-      # before it projects, so the fresh read above has already replayed
-      # this very entry off the journal. What the memoized `store` last
-      # held — from before this call — is read up front, for the return
-      # value only; it plays no part in what gets written.
+      # On a delete the fresh read has already replayed the entry, so the returned record
+      # comes from the memoized `store`, read up front.
       #
       # @param entry [Persistence::Entry] the save or delete to materialize
       # @return [Runtime::Instance, nil] on a save, the newly stored record; on a delete, the
@@ -178,10 +163,7 @@ module Hecks
       # @return [Array<Runtime::Event>] the adapter's in-memory event log, including `event`
       def record_event(event) = @events << event
 
-      # ── the optional saga-persistence capability (§2) — Heki's own
-      # shape (a sibling snapshot+journal file pair, `SagaStore`,
-      # heki/saga_store.rb) rather than a table in a store this adapter
-      # doesn't have.
+      # Checkpoints one saga instance in a sibling file pair (`SagaStore`).
       #
       # @param process_manager [String, Symbol] the process manager's name, compared as
       #   `.to_s`
@@ -209,18 +191,15 @@ module Hecks
         saga_store.delete_saga(@domain, process_manager.to_s, correlation.to_s)
       end
 
-      # Yields every checkpointed saga instance of this domain, for `Registry
-      # #rehydrate_sagas!` to restore at boot.
+      # Yields every checkpointed saga instance of this domain, for boot-time rehydration.
       #
       # @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 none was recorded
-      # @return [Enumerator, Hash{String => Hash}] an enumerator over the same five values
-      #   when no block is given; otherwise `SagaStore`'s 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(&) = saga_store.each_saga(@domain, &)
 
       private
@@ -229,8 +208,6 @@ module Hecks
         @saga_store ||= SagaStore.new(File.dirname(@path))
       end
 
-      # `record` is the snapshot/journal's own string-keyed JSON — decoded
-      # deep through the state codec, never symbolized one level by hand.
       def instance(id, record)
         Runtime::Instance.new(
           aggregate: @aggregate,
@@ -248,13 +225,7 @@ module Hecks
         replay_journal(snapshot)
       end
 
-      # `dir: :default` — a bare Symbol, the framework's own convention
-      # for "a declared value that resolves by convention, never a silent
-      # fallback" — would otherwise crash `File.join` outright
-      # (`TypeError: no implicit conversion of Symbol into String`):
-      # `resolve_path` only ever checked for a missing `dir` setting,
-      # never a Symbol one. Treated the same as no setting at all — falls
-      # back to the existing "data" default, not a new special case.
+      # `dir: :default` means no setting; a Symbol would make `File.join` raise TypeError.
       def resolve_path(settings, root)
         declared =
           if settings.key?(:dir)

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

@@ -1,22 +1,13 @@
 module Hecks
   module Adapters
-    # The `identity_resolution` port, fulfilled by the Identity framework
-    # bluebook — same registry, same boot, so this is a dispatch against
-    # records already sitting in the store this adapter is handed, not a
-    # bridge to a second runtime. Same reasoning `GovernanceAuthorization`
-    # gives for itself, one port over.
+    # The `identity_resolution` port, fulfilled by the Identity framework bluebook
+    # through a dispatch on the same registry.
     module IdentityRegistry
       module_function
 
       # Looks up the id of the identity an authenticated (issuer, subject) pair is linked to,
       # querying the Identity framework bluebook's own `ResolvedBy`.
       #
-      # `nil` for a pair nothing has linked, the first match otherwise —
-      # `ResolvedBy` is a lookup by the exact (issuer, subject) an
-      # authenticated token carries, not a listing, so more than one row
-      # would mean two links share a pair, which `Link`'s own natural
-      # key already prevents by construction.
-      #
       # @param registry [Runtime::Registry] the booted registry, queried for the linked
       #   identity's id
       # @param issuer [String] the OIDC issuer that authenticated the caller, compared as a
@@ -24,9 +15,7 @@ module Hecks
       # @param subject [String] the OIDC subject the issuer vouches for, compared as a String
       # @return [String, nil] the linked identity's id, or nil if nothing has linked this pair
       def resolve(registry, issuer:, subject:)
-        # The resolve verb this registry's declared identity provider names
-        # (`provides "identity", resolve:`), never a hard-coded chapter —
-        # same declared-not-named shape GovernanceAuthorization already holds.
+        # The verb comes from the declared identity provider (`provides "identity", resolve:`).
         provider = registry.bluebooks.values.find { |chapter| chapter.provides?(::Hecks::Bluebook::Capabilities::IDENTITY) }
         verb = provider&.provided_verb(::Hecks::Bluebook::Capabilities::IDENTITY, :resolve) ||
                "Identity::ExternalIdentifier.ResolvedBy"