hecks 1.2.0 → 1.4.0

data/lib/hecks/ports/persistence/plugins/era.rb

@@ -11,7 +11,7 @@ module Hecks
   module Ports
     module Persistence
       module Plugins
-        # ADR 0033 — requiring THIS FILE is installing the plugin. Nothing in
+        # ADR 0033 — requiring this file is installing the plugin. Nothing in
         # Hecks core requires it; an app that binds `PostgresEra`, or wants
         # schema-translation support at all, requires it explicitly — the
         # same shape every adapter-specific spec fixture already uses to
@@ -19,6 +19,8 @@ module Hecks
         module Era
           module_function
 
+          # Registers this plugin's era gates on one boot's gate list.
+          #
           # `Runtime::Loader.run_boot_gates!` asks every loaded persistence
           # plugin to contribute here, generically — it never mentions
           # `EraCheck` or "era" by name. Two gates, both `:pre_verify`:
@@ -29,11 +31,19 @@ module Hecks
           # unchanged) — this is the rich, adapter-aware version of that
           # check; `Runtime::Loader`'s own structural backstop (plain
           # `Bluebook::Translation` data, no plugin-specific class) only
-          # ever fires when NO persistence plugin is loaded at all.
+          # ever fires when no persistence plugin is loaded at all.
           #
           # `:era_check` — conditional, exactly ADR 0031's own gate,
           # unchanged: registered only when this registry has an aggregate
           # actually bound to a lineage-capable adapter.
+          #
+          # @param registry [Runtime::Registry] the registry being booted, asked whether any
+          #   bluebook's first aggregate is bound to a lineage-capable adapter
+          # @param gates [Runtime::BootGates] this boot's gate list, registered onto in place
+          # @return [Runtime::BootGates, nil] `gates` when `:era_check` was registered; nil when
+          #   the registry binds nothing lineage-capable, so only `:era_compute_rules` was added
+          # @raise [Runtime::WiringError] if an aggregate's persistence binding is missing,
+          #   ambiguous, or carries an unsupported role
           def contribute_boot_gates(registry, gates)
             gates.register(:era_compute_rules, lambda { |reg, _dir|
               Runtime::EraCheck.check_compute_rules_for_registry!(reg)

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

@@ -3,12 +3,12 @@ require_relative "../../runtime/registry"
 module Hecks
   module Ports
     module Persistence
-      # THE OTHER SHAPE AN ADAPTER CAN BE. `AppendOnly` names one shape
+      # The other shape an adapter can be. `AppendOnly` names one shape
       # already — something that stores bytes, locally (Postgres, SQLite,
       # Heki) or over the network (D1), doesn't matter, the point is it
       # does real local interpretation and has real entries to replay.
       # This names the second, different shape: not "storage reached
-      # remotely," but the real INTERPRETER itself living behind a call
+      # remotely," but the real interpreter itself living behind a call
       # boundary — `append`/`project` don't do partial local work and
       # then fail, they raise unconditionally, because there is no local
       # write-ahead log to have; `entries` is always `[]` for the same
@@ -28,6 +28,10 @@ module Hecks
       # `Runtime::RemoteDispatcher`'s own use) instead of comparing
       # adapter names by string.
       module RemoteRuntime
+        # Refuses every local write; `project` is an alias and refuses the same way.
+        #
+        # @return [void] never returns
+        # @raise [Runtime::WiringError] always, pointing the caller at `Runtime::RemoteDispatcher`
         def append(*)
           raise Runtime::WiringError,
                 "#{self.class.name} is a remote-runtime delegate — dispatch through " \
@@ -35,6 +39,9 @@ module Hecks
         end
         alias project append
 
+        # Reports an empty journal, since a remote-runtime delegate keeps no local log.
+        #
+        # @return [Array] always `[]`
         def entries = []
       end
     end

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

@@ -1,27 +1,50 @@
 require_relative "append_only"
+require_relative "codec_boundary"
 
 module Hecks
   module Ports
     module Persistence
       # Turns a declared adapter binding plus its world configuration into a
       # concrete repository. Selection policy stays out of adapter creation.
+      #
+      # Every adapter it builds is guarded (`CodecBoundary.guard!`) before
+      # anything else touches it — `recover!` included — so no adapter a
+      # runtime reaches can build an `Instance` from undecoded state.
       module RepositoryFactory
         module_function
 
+        # Instantiates the adapter a bind names, guards it, and wraps it as a repository.
+        #
+        # @param registry [Runtime::Registry] the registry supplying the adapter class, the
+        #   domain's world settings, its resolved eras and the root path
+        # @param domain [String, Symbol] name of the domain the aggregate belongs to
+        # @param aggregate [Bluebook::Aggregate] the aggregate to persist
+        # @param bind [Bluebook::Bind] the bind naming the adapter, as `BindingPolicy.resolve`
+        #   or the projection port chose it
+        # @param recover [Boolean] true to replay the journal through `project` before returning
+        # @param settings_verb [String] the verb whose world settings configure the adapter;
+        #   `"persisted_by"` by default, `Ports::Projection::VERB` for a projection
+        # @return [Persistence::AppendOnly] the repository over the guarded adapter
+        # @raise [Runtime::WiringError] if the bind's verb or settings fail the registry's
+        #   checks, no `Hecks::Adapters` constant matches the adapter name, or the adapter
+        #   lacks `append`, `project` or `entries`
         def build(registry, domain, aggregate, bind, recover: true, settings_verb: VERB)
           registry.check_verb(bind)
           settings = (registry.world(domain)&.for_binding(settings_verb, bind.adapter) || {})
                      .reject { |key, _| key.to_sym == :role }
           registry.check_settings(bind, settings)
-          # The domain and the resolved era ride along after the
-          # declared-settings check: a lineage adapter journals per
-          # DOMAIN and writes into its own ERA's partition — neither of
-          # which a world's settings carry.
+          # The domain, the resolved era, and (for an old checkout) the era
+          # that superseded it ride along after the declared-settings
+          # check: a lineage adapter journals per domain, writes into its
+          # own era's partition, and refuses to write at all once that era
+          # is superseded (`PostgresEra#append`, BUG#24) — none of which a
+          # world's settings carry.
           adapter = registry.adapter_class(bind.adapter)
                             .new(aggregate: aggregate,
-                                 settings:  settings.merge(domain: domain.to_s, era: registry.resolved_eras[domain.to_s]),
+                                 settings:  settings.merge(domain: domain.to_s, era: registry.resolved_eras[domain.to_s],
+                                                           superseded_by: registry.superseded_eras[domain.to_s]),
                                  root:      registry.root)
-          repository = AppendOnly.new(adapter)
+          repository = AppendOnly.new(CodecBoundary.guard!(adapter))
           recover ? repository.recover! : repository
         end
       end

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

@@ -0,0 +1,319 @@
+require "json"
+require_relative "../../runtime/value"
+
+module Hecks
+  module Ports
+    module Persistence
+      # One spelling of an aggregate's state across the store boundary
+      # (Phase 2, Track A, PR A2). This codec is the single, IR-driven
+      # answer every adapter converges on, because adapters left to decode
+      # their own way disagree: symbolizing the top level only (a Heki head,
+      # a journal reader), symbolizing deep (a SQL or Lambda head), or never
+      # serializing at all (Memory's shallow `state.dup`).
+      # spec/ports/persistence_legacy_decode_spec.rb pins that bytes written
+      # without the codec still decode to the one canonical shape. Every
+      # adapter writes through `encode` and reads through `decode`
+      # (Memory through `copy`; PR A3), and `CodecBoundary` — installed on every
+      # adapter `RepositoryFactory.build` makes — refuses an `Instance`
+      # built inside an adapter call from state `decoded?` rejects.
+      #
+      # ## The three operations
+      #
+      # - `encode` — canonical and JSON-ready: string keys at every depth,
+      #   `Runtime::Value`s materialized, only JSON scalars at the leaves.
+      #   Needs no IR (JSON has one spelling), but takes it for symmetry.
+      # - `decode` — walks the aggregate's IR: attributes, value objects
+      #   (their fields, recursively), `list_of` value objects and entities
+      #   (entity fields, nested entities, the entity's own lifecycle),
+      #   references, the lifecycle field, and projected fields. A declared
+      #   key becomes a symbol at every depth, whichever spelling arrived.
+      # - `copy` — `decode(encode(state))`: what a durable adapter would hand
+      #   back, for Memory, with no JSON text in between.
+      #
+      # ## What decode never does
+      #
+      # It never invents a key. A declared field absent from the stored
+      # state stays absent — not a present nil — because the runtime reads
+      # absence as "this record predates the field": `Instance.
+      # hydrate_with_defaults` fills a declared `default:` only when the key
+      # is missing (spec/runtime/hydrate_defaults_spec.rb), Era translation
+      # backfills only `unless state.key?` (era/lineage.rb#translate), and a
+      # required declared-but-absent field reads as a named refusal rather
+      # than nil (spec/runtime/attribute_absence_spec.rb). A present nil
+      # would silently suppress all three. For the same reason it never
+      # drops a key, nil or not: a stored nil stays a stored nil.
+      #
+      # It never touches an undeclared key's value — a retired field, or a
+      # member a value object no longer declares, is exactly what an Era
+      # translation (rename/move/drop) still has to read. Its key keeps its
+      # spelling below the top level; at the top level every key is a
+      # symbol, declared or not, because every adapter has always
+      # symbolized the top level and `Lineage#translate` reads retired
+      # top-level names as symbols.
+      #
+      # ## When both spellings arrive
+      #
+      # When a hash carries both spellings of one declared key, the symbol
+      # spelling wins: it can only have been written by Ruby after the
+      # string one was read.
+      module StateCodec
+        JSON_SCALARS = [String, Integer, Float, TrueClass, FalseClass, NilClass].freeze
+
+        module_function
+
+        # Converts state into its canonical JSON-ready form for a durable adapter to write.
+        #
+        # @param _aggregate [Bluebook::Aggregate, Bluebook::Entity] unused; taken so `encode`
+        #   and `decode` have one signature
+        # @param state [Hash, Runtime::Value, nil] the state to store; nil for a delete entry
+        # @return [Hash{String => Object}, nil] a new Hash with String keys at every depth and
+        #   only JSON scalars, Arrays and Hashes below; nil when `state` is nil
+        def encode(_aggregate, state) = encode_value(state)
+
+        # Respells stored state into the declared shape by walking the aggregate's IR.
+        #
+        # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the construct whose
+        #   declarations name the keys to symbolize
+        # @param raw [Hash, Object, nil] parsed stored state, with keys in either spelling
+        # @return [Hash{Symbol => Object}, Object, nil] a new Hash with every top-level key and
+        #   every declared nested key a Symbol; anything that is not a Hash is returned as given
+        def decode(aggregate, raw)
+          return raw unless raw.is_a?(Hash)
+
+          fields = declared_top_level(aggregate)
+          decode_hash(aggregate, fields, raw, symbolize_undeclared: true)
+        end
+
+        # Deep-copies state into the shape a durable adapter would read back, without JSON text.
+        #
+        # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the construct whose
+        #   declarations name the keys to symbolize
+        # @param state [Hash, Runtime::Value, nil] live state, such as `Instance#state`
+        # @return [Hash{Symbol => Object}, nil] `decode(encode(state))`, sharing no Hash or
+        #   Array with `state`; nil when `state` is nil
+        def copy(aggregate, state) = decode(aggregate, encode(aggregate, state))
+
+        # Maps every declared top-level field name to its attribute.
+        #
+        # The field walk Sqlite::Codec#persisted_fields does for columns,
+        # as name => Attribute (nil for the lifecycle field and projected
+        # fields: bare scalars with no attribute of their own). The same
+        # three sources, the same precedence — an attribute that happens to
+        # share the lifecycle's or a projected field's name keeps its type.
+        # An entity (no `projected_fields` of its own) gets its entity
+        # field set — `decoded?` is asked about any `Instance`, and an
+        # entity is "structurally interchangeable with an aggregate".
+        #
+        # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the construct to walk
+        # @return [Hash{Symbol => Bluebook::Attribute, nil}] a new Hash of field name to
+        #   attribute; nil marks the lifecycle field or a projected field with no attribute
+        def declared_top_level(aggregate)
+          fields = entity_fields(aggregate)
+          return fields unless aggregate.respond_to?(:projected_fields)
+
+          aggregate.projected_fields.each { |field| fields[field.name.to_sym] = nil unless fields.key?(field.name.to_sym) }
+          fields
+        end
+
+        # Checks whether state already has the shape `decode` produces.
+        #
+        # Whether `decode` would hand `state` back unchanged — every
+        # top-level key a Symbol, every declared key below it a Symbol, no
+        # hash carrying both spellings of a declared key. Allocates
+        # nothing; `CodecBoundary` asks it of every `Instance` an adapter
+        # builds. A `Runtime::Value` (hydrated state, a save's own entry)
+        # already is the declared shape, so it answers true.
+        #
+        # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the construct the state
+        #   belongs to
+        # @param state [Hash, Runtime::Value, nil] the state to inspect
+        # @return [Boolean] true when `state` is decoded, and for anything that is not a Hash
+        def decoded?(aggregate, state)
+          return true unless state.is_a?(Hash)
+
+          hash_decoded?(aggregate, declared_top_level(aggregate), state, top: true)
+        end
+
+        # ── encode ──────────────────────────────────────────────────────
+
+        # Encodes one value, recursing through Hashes, Arrays and `Runtime::Value`s.
+        #
+        # @param value [Object] any state value; a `Runtime::Value` is encoded as its `to_h`
+        # @return [Hash{String => Object}, Array, String, Integer, Float, Boolean, nil] the
+        #   JSON-ready form; a leaf outside `JSON_SCALARS` (a Symbol, a Time) becomes whatever
+        #   a `JSON.generate` then `JSON.parse` round trip makes of it
+        def encode_value(value)
+          case value
+          when Runtime::Value then encode_value(value.to_h)
+          when Hash then value.each_with_object({}) { |(key, inner), out| out[key.to_s] = encode_value(inner) }
+          when Array then value.map { |inner| encode_value(inner) }
+          when *JSON_SCALARS then value
+          # A Symbol, a Time, anything else: exactly what `JSON.generate`
+          # then `JSON.parse` would make of it, so Memory's copy and a
+          # durable adapter's row agree on the leaf too.
+          else JSON.parse(JSON.generate([value])).first
+          end
+        end
+
+        # ── decode ──────────────────────────────────────────────────────
+
+        # Decodes one Hash level, symbolizing its declared keys and recursing into their values.
+        #
+        # `fields` is name => Attribute-or-nil for this level. Key order is
+        # kept; a string key is skipped when the same hash also holds its
+        # symbol spelling, so the symbol wins wherever either one sits.
+        #
+        # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the root construct, through
+        #   which nested value objects and entities resolve
+        # @param fields [Hash{Symbol => Bluebook::Attribute, nil}] the fields declared at
+        #   this level
+        # @param raw [Hash] the stored Hash for this level
+        # @param symbolize_undeclared [Boolean] true to symbolize undeclared keys too, as the
+        #   top level does; false to leave their spelling alone
+        # @return [Hash] a new Hash in `raw`'s key order
+        def decode_hash(aggregate, fields, raw, symbolize_undeclared: false)
+          raw.each_with_object({}) do |(key, value), out|
+            name = key.to_s.to_sym
+            next if key.is_a?(String) && raw.key?(name)
+
+            if fields.key?(name)
+              out[name] = decode_field(aggregate, fields[name], value)
+            else
+              out[symbolize_undeclared ? name : key] = value
+            end
+          end
+        end
+
+        # Decodes the stored value of one declared field.
+        #
+        # One declared field's value, by the four shapes `Value::Coercion`
+        # names (scalar / list / optional / composite). nil, a reference (a
+        # bare id or a list of them), and a scalar pass through untouched; a
+        # value object or entity recurses only when the stored value really
+        # is the Hash/Array its declaration says — anything else (a legacy
+        # bare scalar for a one-field value object) is left for hydration.
+        #
+        # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the root construct, through
+        #   which the field's type resolves
+        # @param attribute [Bluebook::Attribute, nil] the field's declaration; nil for a
+        #   lifecycle or projected field
+        # @param value [Object, nil] the stored value
+        # @return [Object, nil] `value` itself when nothing needs respelling, otherwise a new
+        #   Hash or Array of decoded composites
+        def decode_field(aggregate, attribute, value)
+          return value if attribute.nil? || value.nil? || attribute.reference?
+
+          if attribute.list?
+            return value unless value.is_a?(Array)
+
+            value.map { |element| decode_composite(aggregate, attribute.type.to_s, element) }
+          else
+            decode_composite(aggregate, attribute.type.to_s, value)
+          end
+        end
+
+        # Decodes one stored value object or entity, looked up by type name.
+        #
+        # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the root construct that
+        #   declares, or whose chapter declares, the type
+        # @param type [String] the declared type name, such as `"Address"`
+        # @param value [Object] the stored value
+        # @return [Hash, Object] a new decoded Hash; `value` unchanged when it is not a Hash or
+        #   `type` names neither an entity nor an unambiguous value object
+        def decode_composite(aggregate, type, value)
+          return value unless value.is_a?(Hash)
+
+          entity = Runtime::Value.find_entity(aggregate, type)
+          return decode_hash(aggregate, entity_fields(entity), value) if entity
+
+          value_object = Runtime::Value.value_object_for(aggregate, type)
+          return value unless value_object
+
+          decode_hash(aggregate, value_object.attributes.to_h { |field| [field.name, field] }, value)
+        end
+
+        # Maps an entity's (or aggregate's) attribute names, plus its lifecycle field, to
+        # their attributes.
+        #
+        # An entity is "structurally interchangeable with an aggregate"
+        # (behaviour/entity.rb): its attributes plus its own lifecycle field.
+        # Its value objects and nested entities resolve through the root
+        # aggregate, the same way `EntityListCoercion#hydrate_entity_list`
+        # resolves them.
+        #
+        # @param entity [Bluebook::Entity, Bluebook::Aggregate] the construct to walk
+        # @return [Hash{Symbol => Bluebook::Attribute, nil}] a new Hash of field name to
+        #   attribute; nil marks a lifecycle field that no attribute declares
+        def entity_fields(entity)
+          fields = entity.attributes.to_h { |attribute| [attribute.name, attribute] }
+          lifecycle = entity.lifecycle
+          fields[lifecycle.field.to_sym] = nil if lifecycle && !fields.key?(lifecycle.field.to_sym)
+          fields
+        end
+
+        # ── decoded? ────────────────────────────────────────────────────
+
+        # Checks one Hash level for keys `decode` would respell.
+        #
+        # The mirror of `decode_hash`: a key `decode` would respell (any
+        # non-Symbol at the top, a non-Symbol declared key below it) means
+        # "not decoded"; an undeclared nested key keeps whatever spelling
+        # it has, exactly as `decode` keeps it.
+        #
+        # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the root construct, through
+        #   which nested types resolve
+        # @param fields [Hash{Symbol => Bluebook::Attribute, nil}] the fields declared at
+        #   this level
+        # @param hash [Hash] the Hash to inspect
+        # @param top [Boolean] true for the top level, where every key must be a Symbol
+        # @return [Boolean] true when this level and every declared composite below it is
+        #   decoded
+        def hash_decoded?(aggregate, fields, hash, top: false)
+          hash.all? do |key, value|
+            if key.is_a?(Symbol)
+              !fields.key?(key) || field_decoded?(aggregate, fields[key], value)
+            else
+              !top && !fields.key?(key.to_s.to_sym)
+            end
+          end
+        end
+
+        # Checks the stored value of one declared field, the mirror of `decode_field`.
+        #
+        # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the root construct, through
+        #   which the field's type resolves
+        # @param attribute [Bluebook::Attribute, nil] the field's declaration; nil for a
+        #   lifecycle or projected field
+        # @param value [Object, nil] the value to inspect
+        # @return [Boolean] true when `decode_field` would leave `value` as it is; always true
+        #   for nil, a reference, an undeclared attribute, or a list that is not an Array
+        def field_decoded?(aggregate, attribute, value)
+          return true if attribute.nil? || value.nil? || attribute.reference?
+          return composite_decoded?(aggregate, attribute.type.to_s, value) unless attribute.list?
+
+          !value.is_a?(Array) || value.all? { |element| composite_decoded?(aggregate, attribute.type.to_s, element) }
+        end
+
+        # Checks one stored value object or entity, the mirror of `decode_composite`.
+        #
+        # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the root construct that
+        #   declares, or whose chapter declares, the type
+        # @param type [String] the declared type name
+        # @param value [Object] the value to inspect
+        # @return [Boolean] true when `value` is not a Hash, `type` names neither an entity nor
+        #   an unambiguous value object, or every declared key in it is a Symbol
+        def composite_decoded?(aggregate, type, value)
+          return true unless value.is_a?(Hash)
+
+          entity = Runtime::Value.find_entity(aggregate, type)
+          return hash_decoded?(aggregate, entity_fields(entity), value) if entity
+
+          value_object = Runtime::Value.value_object_for(aggregate, type)
+          return true unless value_object
+
+          hash_decoded?(aggregate, value_object.attributes.to_h { |field| [field.name, field] }, value)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/ports/persistence.rb

@@ -15,6 +15,7 @@ require_relative "persistence/append_only"
 require_relative "persistence/execution"
 require_relative "persistence/remote_runtime"
 require_relative "persistence/null_saga_store"
+require_relative "persistence/state_codec"
 
 module Hecks
   module Ports
@@ -25,16 +26,50 @@ module Hecks
     module Persistence
       module_function
 
-      # The public persistence port owns only authoritative aggregate heads.
+      # Builds the repository that reads and writes one aggregate's authoritative store.
+      #
+      # The public persistence port owns only authoritative aggregate heads. The repository
+      # comes back already recovered: every journal entry has been re-projected.
+      #
+      # @param registry [Runtime::Registry] the booted registry holding the domain's
+      #   hecksagon, world and adapters
+      # @param domain [String, Symbol] name of the domain the aggregate belongs to
+      # @param aggregate [Bluebook::Aggregate] the aggregate to persist
+      # @return [Persistence::AppendOnly] repository over the aggregate's authoritative
+      #   adapter, or over a `Memory` adapter when the domain declares no hecksagon
+      # @raise [Runtime::WiringError] if the aggregate has no authoritative bind, more than
+      #   one, or a bind with a role this port does not support; or if the bound adapter is
+      #   unknown, answers a different verb, is given a setting it does not declare, has no
+      #   Ruby implementation, or lacks a method its port's `answers` list or the
+      #   append-only contract (`append`, `project`, `entries`) requires
       def repository(registry, domain, aggregate)
         authoritative = BindingPolicy.resolve(registry, domain, aggregate)
         RepositoryFactory.build(registry, domain, aggregate, authoritative)
       end
 
+      # Resolves an aggregate's authoritative bind, paired with an always-empty Array.
+      #
+      # @param registry [Runtime::Registry] the booted registry holding the domain's hecksagon
+      # @param domain [String, Symbol] name of the domain the aggregate belongs to
+      # @param aggregate [Bluebook::Aggregate] the aggregate whose binding is wanted
+      # @return [Array(Bluebook::Bind, Array)] the authoritative `persisted_by` bind (the
+      #   default `Memory` bind when the domain declares no hecksagon), then an Array that
+      #   is always `[]`
+      # @raise [Runtime::WiringError] if the aggregate has no authoritative bind, more than
+      #   one, or a bind with a role this port does not support
       def binds_for(registry, domain, aggregate)
         [BindingPolicy.resolve(registry, domain, aggregate), []]
       end
 
+      # Resolves the one bind naming an aggregate's authoritative store.
+      #
+      # @param registry [Runtime::Registry] the booted registry holding the domain's hecksagon
+      # @param domain [String, Symbol] name of the domain the aggregate belongs to
+      # @param aggregate [Bluebook::Aggregate] the aggregate whose binding is wanted
+      # @return [Bluebook::Bind] the authoritative `persisted_by` bind, or the default
+      #   `Memory` bind when the domain declares no hecksagon
+      # @raise [Runtime::WiringError] if the aggregate has no authoritative bind, more than
+      #   one, or a bind with a role this port does not support
       def bind_for(registry, domain, aggregate)
         binds_for(registry, domain, aggregate).first
       end

data/lib/hecks/ports/projection.rb

@@ -12,10 +12,32 @@ module Hecks
 
       module_function
 
+      # Lists the `projected_by` binds a domain's hecksagon declares for one aggregate.
+      #
+      # @param registry [Runtime::Registry] the booted registry to search
+      # @param domain [String, Symbol] name of the domain the aggregate belongs to
+      # @param aggregate [Bluebook::Aggregate] the aggregate to find projection binds for
+      # @return [Array<Bluebook::Bind>] the binds naming the aggregate, or failing that the
+      #   hecksagon's aggregate-less `projected_by` binds; `[]` if there are none or the
+      #   domain declares no hecksagon
       def binds_for(registry, domain, aggregate)
         registry.hecksagon(domain)&.binds_for(aggregate.hecks_name, VERB) || []
       end
 
+      # Builds a worker that catches one projection's store up to its authoritative journal.
+      #
+      # @param registry [Runtime::Registry] the booted registry to resolve binds against
+      # @param domain [String, Symbol] name of the domain the aggregate belongs to
+      # @param aggregate [Bluebook::Aggregate] the aggregate being projected
+      # @param policy [Symbol, String] `:refresh` (reset the store and rebuild it) or
+      #   `:strict` (refuse on divergent history) — see `Worker::VALID_POLICIES`
+      # @return [Ports::Projection::Worker, nil] a worker for the aggregate's first declared
+      #   bind, or nil if it has no projection bind
+      # @raise [Runtime::WiringError] if the aggregate's authoritative persistence bind does
+      #   not resolve (see `Persistence.repository`), or the projection's adapter is unknown,
+      #   answers a different verb, is given a setting it does not declare, has no Ruby
+      #   implementation, or lacks a method the append-only contract requires
+      # @raise [ArgumentError] if `policy` is not one of `Worker::VALID_POLICIES`
       def worker(registry, domain, aggregate, policy: :refresh)
         bind = binds_for(registry, domain, aggregate).first
         return unless bind
@@ -32,23 +54,32 @@ module Hecks
       # separate process or scheduler, never from the command-side write
       # path.
       class Worker
+        # @return [Persistence::AppendOnly] the projection store this worker catches up
         attr_reader :projection
 
         # The only two policies anything in this codebase ever passes
         # (`bin/project`, every spec) — there is no third, legitimate
-        # "lenient append" policy on record anywhere. Before this, any
-        # value OTHER than the exact symbol `:strict` silently fell
-        # through the `consistent?` check below and appended onto
-        # divergent history without a word — not just a real typo like
-        # `:strikt`, but a caller-supplied String `"strict"` too (this
-        # duck-typed fine via `policy.to_sym`, but that was luck, not a
-        # contract: nothing here declared what a valid policy even was).
+        # "lenient append" policy on record anywhere. This list is the
+        # contract for what a valid policy is: `catch_up!` enforces
+        # history agreement only for the exact symbol `:strict`, so any
+        # other unrecognised value — a typo like `:strikt` — would fall
+        # through the `consistent?` check below and append onto
+        # divergent history without a word. A caller-supplied String
+        # `"strict"` is accepted on purpose, normalised by `policy.to_sym`
+        # in `initialize` before it is checked against this list, not by
+        # the accident of duck typing.
         # Refusing loudly at construction, once, for anything outside
         # this list turns a silent no-op into an immediate, named error
         # — the "refuse rather than silently skip" reading of L1, since
         # `:strict` really is meant to be the only enforcing contract.
         VALID_POLICIES = %i[refresh strict].freeze
 
+        # @param authoritative [Persistence::AppendOnly] the authoritative repository whose
+        #   journal the projection is caught up to
+        # @param projection [Persistence::AppendOnly] the projection store being caught up
+        # @param policy [Symbol, String] one of `VALID_POLICIES`, as a Symbol or its String
+        #   spelling
+        # @raise [ArgumentError] if `policy` is not one of `VALID_POLICIES`
         def initialize(authoritative, projection, policy: :refresh)
           @authoritative = authoritative
           @projection = projection
@@ -60,8 +91,20 @@ module Hecks
           end
         end
 
+        # Appends and projects every authoritative entry the projection store lacks.
+        #
         # Invoke from a separate process or scheduler. The command-side write
         # path never calls this method.
+        #
+        # Under `:refresh` the store is reset first and rebuilt from the whole journal. Under
+        # `:strict` the store's own entries must be a prefix of the authoritative journal
+        # (same operation, id and state, in order); only the entries after that prefix are
+        # replayed.
+        #
+        # @return [Persistence::AppendOnly] the projection store, now caught up
+        # @raise [Runtime::WiringError] under `:strict`, if the projection's history is not a
+        #   prefix of the authoritative journal; under `:refresh`, if the projection's
+        #   adapter cannot `reset!`
         def catch_up!
           entries = Queue.new(@authoritative).entries
           present = @projection.entries
@@ -79,6 +122,10 @@ module Hecks
           @projection
         end
 
+        # Counts the entries the projection store holds, which is how far it has caught up.
+        #
+        # @return [Integer] number of journal entries already appended to the projection
+        #   store; 0 for a store that has never caught up
         def checkpoint = @projection.entries.length
 
         private
@@ -96,7 +143,14 @@ module Hecks
       # It is committed before a worker sees it; projection entries are the
       # worker's durable checkpoint, so delivery is at-least-once and safe to replay.
       class Queue
+        # @param authoritative [Persistence::AppendOnly] the authoritative repository to read
+        #   entries from
         def initialize(authoritative) = @authoritative = authoritative
+
+        # Reads the whole authoritative journal, the work a projection worker replays from.
+        #
+        # @return [Array<Persistence::Entry>] every committed entry, oldest first; `[]` for
+        #   an empty journal
         def entries = @authoritative.entries
       end
     end

data/lib/hecks/ports/query/in_memory.rb

@@ -27,7 +27,7 @@ module Hecks
           field   = declared.order_by&.field
           matched = Ordering.apply(matched, declared.order_by, declared.null_semantics,
                                    identity: ->(record) { record.id.to_s }) { |record| comparable(FieldPath.dig(record, field)) }
-          # OFFSET FIRST, THEN LIMIT — the order SQL means by `LIMIT n
+          # **Offset first, then limit** — the order SQL means by `LIMIT n
           # OFFSET m`, which is what `SqlQueryBuilder` emits and therefore
           # what every SQL-backed aggregate already answers. Written the
           # other way round here, and the two engines disagreed on the
@@ -38,7 +38,7 @@ module Hecks
           #
           # It gets worse the further you page, which is the case nobody
           # writing the first page ever sees: at `limit 10, offset 10`,
-          # taking ten and then dropping ten leaves NOTHING, so page two
+          # taking ten and then dropping ten leaves nothing, so page two
           # of a memory-backed query came back empty however many rows
           # were really there.
           matched = matched.drop(resolve(declared.offset.value, args).to_i) if declared.offset
@@ -50,7 +50,7 @@ module Hecks
         # QuerySpecification::Common::Comparison — this module and
         # Runtime::QueryInterpreter used to carry a copy each, and the two
         # drifted (see that file's own comment for what it cost). What
-        # stays here is how a value is REACHED for this path: a registry
+        # stays here is how a value is reached for this path: a registry
         # arrives as an argument rather than as instance state, and the
         # field is dug through FieldPath before it arrives.
         def holds?(clause, held, args, registry: nil)