hecks 2.7.0 → 2.9.0

data/lib/hecks/ports/persistence/append_only.rb

@@ -6,7 +6,12 @@ module Hecks
     module Persistence
       # `mirrors` is durable replication intent.  It is part of the same
       # append as the authoritative state, never a second outbox store.
-      Entry = Struct.new(:operation, :id, :state, :mirrors, keyword_init: true) do
+      #
+      # `sequence` is the journal position an adapter assigned this entry
+      # (set by `append` on a live write, or by `entries`/`entries_since` on
+      # a replayed one); nil for an adapter that assigns none. It rides
+      # along so `project` can advance a checkpoint without a second lookup.
+      Entry = Struct.new(:operation, :id, :state, :mirrors, :sequence, keyword_init: true) do
         # Tells a projecting adapter that this entry writes a record.
         #
         # @return [Boolean] true when `operation` is the String `"save"`
@@ -18,9 +23,8 @@ module Hecks
         def delete? = operation == "delete"
       end
 
-      # Makes append-before-projection a port invariant. Adapters retain
-      # control of their durable format, but every one must accept the same
-      # entry stream and materialize current state from it.
+      # Makes append-before-projection a port invariant: adapters keep their own durable
+      # format, but must accept the same entry stream and materialize state from it.
       class AppendOnly
         attr_reader :adapter
 
@@ -71,6 +75,17 @@ module Hecks
         #   undecoded (`CodecBoundary.check_entries!`)
         def entries = @adapter.entries
 
+        # Reads how far this repository's journal has been compacted, when the adapter tracks
+        # that (Postgres, Sqlite).
+        #
+        # @return [Integer] the highest journal `sequence` already deleted by compaction; 0 for
+        #   an adapter that tracks no such thing, or nothing compacted yet
+        def compacted_through
+          return 0 unless @adapter.respond_to?(:compacted_through)
+
+          @adapter.compacted_through
+        end
+
         # Lists the optional persistence behaviours the adapter advertises.
         #
         # @return [Array<Symbol>] frozen capability names such as `:atomic_put`,
@@ -96,12 +111,8 @@ module Hecks
 
         # Reads the events the adapter has durably recorded.
         #
-        # Not an endless `def events = ... if ...` — that modifier binds to
-        # the whole `def`, not just its body, so it evaluates against
-        # `@adapter` while `@adapter` is still nil (class-body time,
-        # before `initialize` ever runs) and silently skips defining the
-        # method at all. Found live: nothing in this codebase called
-        # `AppendOnly#events` before Memory got a `reset!` test that did.
+        # Written as an `if` guard, not a trailing modifier, which would evaluate against
+        # `@adapter` before `initialize` runs and silently skip defining the method.
         #
         # @return [Array<Runtime::Event>, nil] recorded events, oldest first; nil when the
         #   adapter keeps no event log
@@ -109,15 +120,39 @@ module Hecks
           @adapter.events if @adapter.respond_to?(:events)
         end
 
-        # Replays the whole journal through `project` to rebuild the projected records.
+        # Reads back one record's durably recorded events, oldest first, scoped by the
+        # adapter itself when it can (a SQL adapter pushes this down as a `WHERE` clause
+        # instead of `#events`'s whole-table read); falls back to filtering `#events` for
+        # an adapter with no scoped lookup of its own.
         #
-        # An append is durable before a projection is attempted. Replaying the
-        # log restores a snapshot/table after a crash in that small window.
+        # @param aggregate [String] the `"domain::AggregateName"` key events are stored under
+        # @param id [String, Object] the record's identity, matched as `id.to_s`
+        # @return [Array<Runtime::Event>, nil] the record's events; nil when the adapter
+        #   keeps no event log at all
+        def events_for(aggregate:, id:)
+          return @adapter.events_for(aggregate: aggregate, id: id) if @adapter.respond_to?(:events_for)
+
+          events&.select { |event| event.aggregate == aggregate && event.id.to_s == id.to_s }
+        end
+
+        # Replays unprojected journal entries through `project` to rebuild the projected records.
+        #
+        # An append is durable before a projection is attempted; replaying restores a
+        # snapshot/table after a crash in that small window. Postgres and Sqlite keep their
+        # projected table in the same transaction as the journal append, so they never fall
+        # behind it — each tracks how far it has replayed (`checkpoint`) and only re-walks
+        # entries past that point (`entries_since`), bounded by activity since the last boot,
+        # not total history. An adapter without that pair (Memory, Heki, D1, PostgresEra,
+        # RemoteRuntime) is unaffected: it still replays every entry.
         #
         # @return [Persistence::AppendOnly] self, so a factory can build and recover in one
         #   expression
         def recover!
-          entries.each { |entry| project(entry) }
+          if @adapter.respond_to?(:checkpoint) && @adapter.respond_to?(:entries_since)
+            @adapter.entries_since(@adapter.checkpoint).each { |entry| project(entry) }
+          else
+            entries.each { |entry| project(entry) }
+          end
           self
         end
 
@@ -142,29 +177,15 @@ module Hecks
 
         # Journals an instance's state, projects it, and reports how the write landed.
         #
-        # Returns an `Outcome`, not a bare `Instance` — every call site
-        # (`CommandInterpreter`/`EntityInterpreter`'s own `step_save`,
-        # `RebuildSweep#refresh`) reads it that way.
-        #
-        # `expected_version:` requests optimistic-concurrency CAS — commit
-        # only if the stored record's version still matches what this
-        # instance was read at. It is `nil` both when a caller explicitly
-        # doesn't want CAS (`RebuildSweep#refresh`'s own projection-field
-        # touch-up, which has no `given` to protect) and when the instance
-        # is brand new (never read from storage, so `instance.version` is
-        # nil) — both cases fall through to the plain, unconditional
-        # `project(entry)` below, byte-for-byte today's behavior. Only an
-        # adapter that both receives a non-nil `expected_version` and
-        # declares `:optimistic_concurrency` gets CAS treatment; every
-        # other adapter/call site is unaffected.
+        # Returns an Outcome, not a bare Instance, so callers can check `:saved` vs `:stale`;
+        # `expected_version:` only triggers CAS on an adapter declaring `:optimistic_concurrency`.
         #
         # @param instance [Runtime::Instance] the record to persist; its `state` is shallow
         #   copied into the entry
         # @param expected_version [Integer, nil] the version the instance was read at, or nil
         #   for an unconditional write
-        # @return [Persistence::Outcome] status `:saved` or `:stale`; on `:saved` its `instance`
-        #   is what the adapter's `project` answered, else the instance passed in; on `:stale`
-        #   it is the instance passed in. The entry is journaled even when the result is `:stale`
+        # @return [Persistence::Outcome] status `:saved` or `:stale`; `instance` is the
+        #   adapter's projected result on `:saved`, else the instance passed in
         # @raise [Runtime::WiringError] when the adapter's `append` or `project` refuses
         def save(instance, expected_version: nil)
           entry = Entry.new(operation: "save", id: instance.id.to_s, state: instance.state.dup)
@@ -218,18 +239,7 @@ module Hecks
 
         # Records one emitted event durably, when the adapter keeps an event log.
         #
-        # Not an endless `def record_event = ... if ...` — same gotcha as
-        # `events` above, and it bit for real here: this guard evaluated
-        # against `@adapter` at class-body time (nil, always false), so
-        # `record_event` was never defined at all. `emission.rb`'s own
-        # `repository.record_event(event) if repository.respond_to?(:record_event)`
-        # therefore never fired for any adapter, ever — every declared
-        # `emits` was computed and reported in `registry.event_log` (an
-        # in-process array, gone at exit) but never durably recorded.
-        # Caught because a live tail of a domain's own persisted events
-        # found nothing to tail. `sqlite_spec.rb`/`postgres_spec.rb`/
-        # `postgres_era_spec.rb` all call `adapter.record_event` directly,
-        # bypassing this wrapper — which is exactly why no spec noticed.
+        # Written as an `if` guard, not a trailing modifier — same reason as `events` above.
         #
         # @param event [Runtime::Event] the event to record
         # @return [Object, nil] adapter-defined write result (an Array for Memory, a driver
@@ -240,17 +250,9 @@ module Hecks
 
         # Runs the block inside the adapter's transaction, or plainly when it has none.
         #
-        # One COMMIT boundary for save + emit + outbox — `Interpreting#
-        # run_dispatch_order` runs the `save` and `emit` steps inside
-        # this block, so an adapter that owns a real transaction
-        # (Sqlite, Postgres) commits the aggregate row, its journal
-        # entry, and the outbox rows together or not at all. An adapter
-        # without one just yields: Memory has nothing to roll back, and
-        # a file adapter's own `with_lock` already serialises its pair
-        # of writes. Nested calls are the adapter's problem to make
-        # re-entrant (both SQL adapters check for an open transaction
-        # first) — a reaction dispatched from inside a drain never nests
-        # here anyway, because draining happens after this block returns.
+        # One commit boundary for save + emit + outbox: an adapter with a real transaction
+        # (Sqlite, Postgres) commits the row, journal entry, and outbox rows together or
+        # not at all; Memory just yields, having nothing to roll back.
         #
         # @yield the writes to commit together; an exception raised inside rolls back an
         #   adapter-owned transaction and propagates
@@ -264,11 +266,9 @@ module Hecks
 
         # Runs the block while holding the adapter's cross-process write lock.
         #
-        # Only an adapter advertising `:cross_process_lock` (PostgresEra —
-        # see ADR 0036) implements this; `run_dispatch_order_with_isolation`
-        # (runtime/interpreting.rb) checks `capabilities` before ever
-        # calling it, so the plain `yield` fallback here only guards
-        # against a stray direct call, not the real dispatch path.
+        # Only PostgresEra advertises `:cross_process_lock` (ADR 0036); the real dispatch
+        # path checks `capabilities` first, so this `yield` fallback only guards a stray
+        # direct call.
         #
         # @yield the dispatch to run with writers serialised
         # @return [Object] adapter-defined; the block's own value when the adapter has no
@@ -279,10 +279,7 @@ module Hecks
           yield
         end
 
-        # **The outbox contract** — four optional adapter methods, probed
-        # together the way `save_saga`/`delete_saga`/`each_saga` are
-        # (`Registry::SagaPersistence`): an adapter either has an outbox
-        # or it doesn't, never half of one. See `Runtime::Outbox`.
+        # An adapter implements the whole outbox contract or none of it (see Runtime::Outbox).
         OUTBOX_METHODS = %i[outbox_enqueue outbox_claim outbox_settle outbox_rows].freeze
 
         # Reports whether the adapter implements the whole outbox contract; the answer is
@@ -308,7 +305,7 @@ module Hecks
         #
         # @param id [Integer] the row id assigned by `outbox_enqueue`
         # @return [Boolean] true when this call claimed the row; false when it is missing or
-        #   no longer pending
+        #   not pending
         def outbox_claim(id) = @adapter.outbox_claim(id)
 
         # Records the final status of a claimed outbox row.

data/lib/hecks/ports/persistence/binding_policy.rb

@@ -4,23 +4,13 @@ require_relative "../../runtime/registry"
 module Hecks
   module Ports
     module Persistence
-      # Resolves one aggregate's persistence topology. An unmarked binding is
-      # authoritative; roles are deliberately opt-in so a second adapter can
-      # never silently become a read source.
+      # Resolves one aggregate's persistence topology; an unmarked binding is
+      # authoritative, and roles are opt-in so no adapter silently becomes a read source.
       module BindingPolicy
         module_function
 
-        # Picks the one bind that names an aggregate's authoritative store.
-        #
-        # A domain with no hecksagon gets the default in-memory bind. A domain that has one
-        # must bind the aggregate exactly once without a role.
-        #
-        # A `default_adapter` a world declares (`Registry#default_adapter_for` — the
-        # chapter's own world, else the project's) stands in wherever the hecksagon binds
-        # nothing for the aggregate, and replaces the in-memory fallback for a domain
-        # with no hecksagon. It is never consulted once the hecksagon binds the aggregate
-        # or declares a domain-level default of its own, so an explicit chapter decision
-        # always wins.
+        # Picks the one bind that names an aggregate's authoritative store. A world's
+        # `default_adapter` only fills a hecksagon's gap; an explicit bind always wins.
         #
         # @param registry [Runtime::Registry] the registry holding the domain's hecksagon
         # @param domain [String, Symbol] name of the domain the aggregate belongs to

data/lib/hecks/ports/persistence/codec_boundary.rb

@@ -4,47 +4,15 @@ require_relative "../../runtime/errors"
 module Hecks
   module Ports
     module Persistence
-      # No adapter can build an `Instance` from undecoded state (Phase 2,
-      # Track A, PR A3). Routing every adapter through `StateCodec` is a
-      # convention until something refuses the bypass; this is that
-      # something, and it is installed by `RepositoryFactory.build` — the
-      # one place every runtime repository is made — so no adapter can opt
-      # out of it.
-      #
-      # ## The mechanism, two halves
-      #
-      # 1. `guard!(adapter)` extends the adapter object (not its class,
-      #    not a proxy — `is_a?`, `class`, and `===` stay the adapter's
-      #    own) with a module that wraps every public method the adapter's
-      #    class defines. Each call runs inside the boundary: a
-      #    thread-local flag, re-entrant, restored on the way out. A block
-      #    the caller passes (`transaction`, `with_write_lock`,
-      #    `each_saga`) runs outside it — that block is the dispatch
-      #    itself (hydrate, entity views, mutation), not adapter code.
-      #    Reaching the adapter through `repository.adapter` (the query
-      #    port, saga persistence, `bin/heki_compact`) is guarded all the
-      #    same: the wrapper is on the object.
-      #
-      # 2. `Runtime::Instance#initialize` asks `check_state!` whenever it
-      #    is handed `state:`. Outside the boundary that is a no-op; inside
-      #    it, state `StateCodec.decoded?` rejects refuses by name. An
-      #    `entries` answer is checked the same way on its way out, since a
-      #    journal `Entry` is not an `Instance`.
-      #
-      # ## Checked, not silently decoded
-      #
-      # An adapter that forgets the codec is a bug in that adapter, and
-      # decoding for it here would hide the forgetting. Hydration does not
-      # respell keys either (A4) — `Value.hydrate` refuses a non-Symbol
-      # top-level key everywhere — so this boundary's deep check and
-      # hydration's shallow one agree.
+      # Refuses to let a guarded adapter build an `Instance` from undecoded state.
+      # `RepositoryFactory.build` installs it, so no adapter can opt out.
       module CodecBoundary
         KEY = :hecks_persistence_codec_boundary
 
         module_function
 
-        # Extends an adapter object so every public method its class defines runs inside the
-        # boundary; guarding an adapter twice wraps it once.
+        # Extends the adapter object so every public method its class defines runs inside the
+        # boundary; guarding twice wraps once.
         #
         # @param adapter [Object] a driven persistence adapter instance
         # @return [Object] the same adapter object, now including `Guarded`
@@ -53,33 +21,22 @@ module Hecks
           adapter
         end
 
-        # Reports whether the current thread is executing inside a guarded adapter call.
+        # Whether this thread is currently inside a guarded adapter call.
         #
-        # @return [Boolean] true between entering a guarded adapter method and yielding to the
-        #   caller's block or returning
+        # @return [Boolean]
         def active? = Thread.current[KEY] == true
 
-        # Runs the block with the boundary switched on for this thread, restoring the earlier
-        # setting afterwards.
-        #
-        # @yield adapter code whose `Instance` construction is to be checked
-        # @return [Object] the block's value
+        # Runs the block with the boundary on for this thread; re-entrant.
         def within(&) = with_flag(true, &)
 
-        # Runs the block with the boundary switched off for this thread, restoring the earlier
-        # setting afterwards.
-        #
-        # @yield caller code, such as a dispatch running inside the adapter's transaction
-        # @return [Object] the block's value
+        # Runs the block with the boundary off for this thread; re-entrant.
         def outside(&) = with_flag(false, &)
 
-        # Refuses state an adapter is about to build an `Instance` from unless it is decoded;
-        # outside the boundary it checks nothing.
+        # Refuses undecoded state headed for `Runtime::Instance.new`; a no-op outside the boundary.
         #
         # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the construct the state
         #   belongs to
         # @param state [Hash, Runtime::Value] the state handed to `Runtime::Instance.new`
-        # @return [nil] when the boundary is inactive or the state is decoded
         # @raise [Runtime::WiringError] if the boundary is active and
         #   `StateCodec.decoded?` rejects the state
         def check_state!(aggregate, state)
@@ -93,13 +50,12 @@ module Hecks
         end
 
         # Refuses a guarded adapter's `entries` answer if any entry's state is undecoded.
+        # A journal `Entry` is not an `Instance`, so `check_state!` never sees it.
         #
-        # @param adapter [Object] the guarded adapter, asked for its `aggregate` and class name
-        # @param entries [Array<Persistence::Entry>, Object] what the adapter's `entries`
-        #   returned; anything that is not an Array passes through unchecked
+        # @param adapter [Object] the guarded adapter
+        # @param entries [Array<Persistence::Entry>, Object] anything but an Array passes unchecked
         # @return [Array<Persistence::Entry>, Object] `entries` itself
-        # @raise [Runtime::WiringError] if an `Entry` in the Array carries state
-        #   `StateCodec.decoded?` rejects
+        # @raise [Runtime::WiringError] if an `Entry` carries state `StateCodec.decoded?` rejects
         def check_entries!(adapter, entries)
           return entries unless entries.is_a?(Array)
 
@@ -113,13 +69,7 @@ module Hecks
           entries
         end
 
-        # Sets the thread-local boundary flag for the length of the block, which is what makes
-        # the boundary re-entrant.
-        #
-        # @param value [Boolean] true to switch the boundary on, false to switch it off
-        # @yield the code to run under that setting
-        # @return [Object] the block's value; the earlier flag is restored even when the
-        #   block raises
+        # Sets the thread-local flag for the block and restores it after, even on a raise.
         def with_flag(value)
           previous = Thread.current[KEY]
           Thread.current[KEY] = value
@@ -128,24 +78,18 @@ module Hecks
           Thread.current[KEY] = previous
         end
 
-        # Marks a guarded adapter so a second `guard!` (a projection and an
-        # authoritative repository built over one object) never wraps twice.
+        # Marks a guarded adapter so a second `guard!` never wraps it twice.
         module Guarded; end
 
-        # Filled lazily under `WRAPPERS_LOCK`, one entry per adapter class —
-        # a cache, deliberately mutable.
+        # A per-adapter-class cache, filled lazily under `WRAPPERS_LOCK`; deliberately mutable.
         WRAPPERS = {} # rubocop:disable Style/MutableConstant
         WRAPPERS_LOCK = Mutex.new
 
         # Builds, or fetches from the cache, the module that guards one adapter class.
-        #
-        # One wrapper module per adapter class, built once: every public
-        # instance method the class (and its ancestors below Object)
-        # defines, each forwarding to `super` inside the boundary.
+        # Each public method forwards to `super` inside the boundary.
         #
         # @param klass [Class] the adapter's class
-        # @return [Module] an anonymous module including `Guarded`, meant to be `extend`ed onto
-        #   instances of `klass`
+        # @return [Module] an anonymous module including `Guarded`, to `extend` onto instances
         def wrapper_for(klass)
           WRAPPERS_LOCK.synchronize do
             WRAPPERS[klass] ||= Module.new do
@@ -161,12 +105,8 @@ module Hecks
           end
         end
 
-        # Wraps the caller's own block so it runs outside the boundary
-        # whenever the adapter yields to it.
-        #
-        # @param block [Proc, nil] the block the caller passed to the adapter method
-        # @return [Proc, nil] a proc forwarding its arguments to `block` under `outside`; nil
-        #   when no block was given
+        # Wraps the caller's block so it runs outside the boundary when the adapter yields to it;
+        # that block is the dispatch itself, not adapter code.
         def outside_block(block)
           return nil unless block
 

data/lib/hecks/ports/persistence/null_saga_store.rb

@@ -1,32 +1,16 @@
 module Hecks
   module Ports
     module Persistence
-      # **The no-op saga store** — what `Registry#saga_persistence` hands
-      # back for a domain whose resolved adapter doesn't implement the
-      # (optional) saga-persistence capability: Memory, deliberately
-      # (sagas stay in-memory-only, exactly as they always have), and
-      # any `RemoteRuntime`-shaped adapter (Lambda; the real durability
-      # for those lives on the other side of the call — Phase 1, not
-      # here). `SagaInterpreter`'s hook points call through
-      # `saga_persistence(domain)` unconditionally; this is what makes
-      # that safe without a `respond_to?` check at every call site,
-      # mirroring the same optional-capability shape
-      # `Ports::Persistence::AppendOnly` already gives adapters that
-      # don't implement `reset!`/`events`/`record_event`.
+      # A saga store that keeps nothing, for adapters without the optional saga-persistence
+      # capability; callers call through it unconditionally instead of checking `respond_to?`.
       class NullSagaStore
-        # Accepts and discards a saga checkpoint, whatever keywords it carries.
-        #
-        # @return [nil] always; nothing is stored
+        # Discards the checkpoint.
         def save_saga(**) = nil
 
-        # Accepts and ignores a request to forget a saga.
-        #
-        # @return [nil] always; there is nothing to delete
+        # Ignores the request; there is nothing to delete.
         def delete_saga(**) = nil
 
         # Yields nothing, because no saga is ever stored here.
-        #
-        # @return [nil] always; a block, if given, is never called
         def each_saga(*) = nil
       end
 

data/lib/hecks/ports/persistence/plugin.rb

@@ -1,28 +1,12 @@
 module Hecks
   module Ports
-    # Reopened to hold the persistence-plugin registry (`Plugin`, below) and
-    # its call surface (`register_plugin`/`plugin?`/`each_plugin`) — see ADR
-    # 0033 and `Plugin`'s own header for the seam this fills.
+    # Holds the persistence-plugin registry and its `register_plugin`/`plugin?`/`each_plugin`
+    # surface.
     module Persistence
-      # A tiny, real seam — ADR 0033. Core never names a persistence plugin;
-      # a plugin makes itself known as a side effect of being `require`d, the
-      # same way an adapter's own `.rb` file already registers itself
-      # (`Runtime::Registry#add_adapter`) rather than core listing adapter
-      # names anywhere. `register_plugin` is the entire contract a plugin
-      # must satisfy: anything responding to `contribute_boot_gates(registry,
-      # gates)` (a no-op is a valid implementation).
+      # The persistence-plugin registry (ADR 0033). A plugin registers itself when required, and
+      # need only respond to `contribute_boot_gates(registry, gates)`; a no-op is valid.
       #
-      # This is deliberately not the same registry `Hecks::Projector` uses
-      # (ADR 0027) or `Runtime::BootGates` (ADR 0031) — each of those is
-      # scoped to its own seam (IR-in/artifact-out; per-boot phased gates).
-      # A shared base is deferred until a third registry actually wants one.
-      #
-      # **Name-keyed, process-wide, not per-boot** — unlike `BootGates` (one
-      # instance per `Loader.boot` call, because gate registration is
-      # capability-conditional per registry), a persistence plugin is either
-      # `require`d into this process or it isn't; there is no "this boot's
-      # registry doesn't need it" case to isolate against, so a plain
-      # module-level hash is the right shape here, not an instantiable class.
+      # Process-wide and name-keyed: a plugin is either required into this process or it is not.
       module Plugin
         @plugins = {}
 
@@ -37,33 +21,25 @@ module Hecks
             @plugins[name.to_sym] = plugin
           end
 
-          # Reports whether a plugin of that name has been required into this process.
+          # Whether a plugin is registered under `name`.
           #
-          # @param name [Symbol, String] the plugin's name
-          # @return [Boolean] true when a plugin is registered under `name`
+          # @return [Boolean]
           def registered?(name)
             @plugins.key?(name.to_sym)
           end
 
           # Yields every registered plugin, in registration order.
-          #
-          # @yieldparam plugin [Object] a registered plugin
-          # @return [Hash{Symbol => Object}, Enumerator] the plugin table when a block is
-          #   given, otherwise an Enumerator over the plugins
           def each(&)
             @plugins.each_value(&)
           end
 
-          # Reports whether any persistence plugin is loaded at all.
+          # Whether at least one plugin is registered.
           #
-          # @return [Boolean] true when at least one plugin is registered
+          # @return [Boolean]
           def any? = !@plugins.empty?
         end
       end
 
-      # `Ports::Persistence.plugin?(:era)` / `.each_plugin` — the ordinary
-      # call surface; `Plugin.register`/`.registered?`/`.each` stay reachable
-      # directly for a plugin's own file to call at require-time.
       module_function
 
       # Registers a persistence plugin; a plugin's own file calls this when it is required.
@@ -73,22 +49,17 @@ module Hecks
       # @return [Object] the plugin just registered
       def register_plugin(name, plugin) = Plugin.register(name, plugin)
 
-      # Reports whether the named persistence plugin is loaded in this process.
+      # Whether the named persistence plugin is loaded in this process.
       #
-      # @param name [Symbol, String] the plugin's name
-      # @return [Boolean] true when a plugin is registered under `name`
+      # @return [Boolean]
       def plugin?(name) = Plugin.registered?(name)
 
       # Yields every loaded persistence plugin, in registration order.
-      #
-      # @yieldparam plugin [Object] a registered plugin
-      # @return [Hash{Symbol => Object}, Enumerator] the plugin table when a block is given,
-      #   otherwise an Enumerator over the plugins
       def each_plugin(&) = Plugin.each(&)
 
-      # Reports whether any persistence plugin is loaded in this process.
+      # Whether any persistence plugin is loaded in this process.
       #
-      # @return [Boolean] true when at least one plugin is registered
+      # @return [Boolean]
       def plugins_loaded? = Plugin.any?
     end
   end