hecks 1.3.0 → 1.5.0

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

@@ -18,6 +18,19 @@ module Hecks
 
         module_function
 
+        # Filters, orders and pages `records` against a declared query specification.
+        #
+        # @param records [Array<Runtime::Instance, Hash>] the candidate records to filter —
+        #   an Instance, a Value, or a plain row hash per record (see `FieldPath.dig`)
+        # @param declared [QuerySpecification::Common::Options,
+        #   Bluebook::Behaviour::ReadModel::FilteredOptions] the specification providing
+        #   `wheres`, `order_by`, `offset` and `limit`
+        # @param args [Hash{Symbol => Object}] bound values for any Symbol placeholder in a
+        #   where clause, `offset`, or `limit`
+        # @param registry [Runtime::Registry, nil] the booted registry, passed through to a
+        #   registry-aware comparison; nil when none is available
+        # @return [Array<Runtime::Instance, Hash>] the matching records, ordered and paged;
+        #   the same element type as `records`
         def execute(records, declared, args = {}, registry: nil)
           matched = records.select do |record|
             declared.wheres.all? do |clause|
@@ -27,7 +40,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 +51,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
@@ -47,18 +60,38 @@ module Hecks
         end
 
         # The comparator table itself lives in
-        # 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
-        # arrives as an argument rather than as instance state, and the
-        # field is dug through FieldPath before it arrives.
+        # QuerySpecification::Common::Comparison, not duplicated per
+        # caller — this module and Runtime::QueryInterpreter drifted
+        # when each carried its own copy (see that file's own comment
+        # for what it cost). What 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.
+        # @param clause [QuerySpecification::Common::WhereClause] the declared comparison
+        # @param held [Object, nil] the record's own value for `clause.field`
+        # @param args [Hash{Symbol => Object}] bound values for a Symbol-named `clause.value`
+        # @param registry [Runtime::Registry, nil] used only by `none_in_state`; see
+        #   `Comparison.holds?`
+        # @return [Boolean] whether the comparison holds
+        # @raise [Runtime::WiringError] if `clause.op` names no comparator in
+        #   `Comparison`'s table, or `none_in_state`'s target aggregate has no wired repository
         def holds?(clause, held, args, registry: nil)
           Comparison.holds?(clause.op, held, comparable(resolve(clause.value, args)), registry: registry)
         end
 
+        # Resolves a where-clause value, looking up a Symbol placeholder in `args`.
+        #
+        # @param value [Object] a literal value, or a Symbol naming a key in `args`
+        # @param args [Hash{Symbol => Object}] bound argument values
+        # @return [Object] `args[value]` when `value` is a Symbol, else `value` unchanged
         def resolve(value, args) = value.is_a?(Symbol) ? args[value] : value
 
+        # Normalises a value into the shape `Comparison` compares against.
+        #
+        # @param value [Runtime::Value, Hash, Object, nil] a held or wanted value; a
+        #   `Runtime::Value` is read through its `to_h`
+        # @return [Object, nil] the sole numeric member, or the sole member, of a Hash-shaped
+        #   value; otherwise `value` unchanged
         def comparable(value) = Comparison.comparable(value)
       end
     end

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

@@ -3,30 +3,45 @@ require_relative "../../query_specification/common/null_policy"
 module Hecks
   module Ports
     module Query
-      # What order an ask ANSWERS IN — the meaning of the ask, not a property
+      # What order an ask answers in — the meaning of the ask, not a property
       # of the store that happens to hold it. Declared here once so an adapter
       # may satisfy it natively but never redefine it : SQLite pushes both
       # tiers into SQL (NullPolicy.sql_order renders `field DIR, id DIR`),
       # while Heki and Memory have no query engine and delegate straight back
       # to InMemory.
       #
-      # Two tiers, in this order : the DECLARED order_by when there is one,
-      # then IDENTITY, always. The identity tier is what makes an ask total.
+      # Two tiers, in this order : the declared order_by when there is one,
+      # then identity, always. The identity tier is what makes an ask total.
       # Without it, an ask with no order_by — or a declared order with tied
       # keys — hands back whatever order the store happened to hold, and
       # store order was quietly standing in for a rule while every
       # hand-written query in the corpus stayed green : not one of them
       # had a tie for store order to decide.
       #
-      # An adapter that pushes ordering down MUST push limit down with it.
+      # An adapter that pushes ordering down must push limit down with it.
       # Re-ordering a page the store already cut would be a top-N of the
       # wrong N — the one way this can be got quietly, expensively wrong.
       module Ordering
         module_function
 
+        # Orders an Array of rows by the declared order, with identity as the total-order
+        # tiebreaker.
+        #
+        # @param rows [Array<Object>] the rows to order; any shape `identity` and the block
+        #   can read (a `Runtime::Instance`, a plain Hash row, …)
+        # @param order_by [QuerySpecification::Common::OrderBy, nil] the declared order;
+        #   nil orders by identity alone
+        # @param null_semantics [QuerySpecification::Common::NullSemantics, nil] where a
+        #   nil-valued row sorts, passed to `NullPolicy.order`; nil uses its native default
+        # @param identity [Proc] yields a row, returns its comparable identity value, used
+        #   as the stable tiebreaker
+        # @yieldparam row [Object] one row being ordered
+        # @yieldreturn [Object, nil] the row's comparable value for `order_by`'s field
+        # @return [Array<Object>] `rows`, ordered by `order_by` then identity (identity
+        #   alone when `order_by` is nil)
         def apply(rows, order_by, null_semantics = nil, identity:, &value_of)
-          # STABLE, because sort_by is not : two rows whose identity ties would
-          # otherwise swap arbitrarily, and a tier meant to REMOVE store-dependence
+          # Stable, because sort_by is not : two rows whose identity ties would
+          # otherwise swap arbitrarily, and a tier meant to remove store-dependence
           # would be adding a coin flip of its own.
           rows = rows.each_with_index.sort_by { |row, index| [identity.call(row), index] }.map(&:first)
           return rows unless order_by