hecks 2.8.0 → 3.0.0

data/lib/hecks/ports/projection.rb

@@ -4,40 +4,18 @@ require_relative "../runtime/registry"
 
 module Hecks
   module Ports
-    # Projection is a read-side port. Its stores are rebuildable consumers of
-    # authoritative entries and never participate in command decisions.
+    # Read-side port: rebuildable stores fed from authoritative entries, never read by commands.
     module Projection
       NAME = "projection".freeze
       VERB = "projected_by".freeze
 
       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`
+      # Builds a worker for the aggregate's first `projected_by` bind; nil when it has none.
       def worker(registry, domain, aggregate, policy: :refresh)
         bind = binds_for(registry, domain, aggregate).first
         return unless bind
@@ -48,38 +26,15 @@ module Hecks
         Worker.new(authoritative, target, policy: policy)
       end
 
-      # Catches one projection's store up to its authoritative journal:
-      # replays whatever entries the store hasn't yet appended/projected.
-      # Constructed via Projection.worker; #catch_up! runs from a
-      # separate process or scheduler, never from the command-side write
-      # path.
+      # Catches one projection store up to its authoritative journal; run from a 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. 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.
+        # Only `:strict` enforces history agreement, so an unknown policy (a typo) would append
+        # onto divergent history silently; construction refuses anything else.
         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
@@ -91,45 +46,55 @@ module Hecks
           end
         end
 
-        # Appends and projects every authoritative entry the projection store lacks.
+        # Appends and projects every authoritative entry the 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!`
+        # `:refresh` never reads journal history — it rebuilds from the aggregate's own current
+        # records, which the authoritative table already holds directly, so it stays correct
+        # past a compacted journal. `:strict` verifies its own entries are a real prefix of the
+        # authoritative journal, which genuinely needs that history; it refuses rather than
+        # silently misreading a compacted journal's surviving rows as if they started at
+        # position zero.
         def catch_up!
-          entries = Queue.new(@authoritative).entries
+          return refresh! if @policy == :refresh
+
+          compacted_through = @authoritative.respond_to?(:compacted_through) ? @authoritative.compacted_through : 0
           present = @projection.entries
-          if @policy == :refresh
-            @projection.reset!
-            present = []
+          if present.length < compacted_through
+            raise Runtime::WiringError,
+                  ":strict catch-up needs journal history the authoritative store has already " \
+                  "compacted (through sequence #{compacted_through}, this projection has only " \
+                  "consumed #{present.length}) — use :refresh instead"
           end
-          unless consistent?(entries, present)
-            raise Runtime::WiringError, "projection history does not match its authoritative history" if @policy == :strict
+
+          entries = Queue.new(@authoritative).entries
+          present_tail = present.drop(compacted_through)
+          unless consistent?(entries, present_tail)
+            raise Runtime::WiringError, "projection history does not match its authoritative history"
           end
-          entries.drop(present.length).each do |entry|
+
+          entries.drop(present_tail.length).each do |entry|
             @projection.append(entry)
             @projection.project(entry)
           end
           @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
 
+        # Resets the store and rebuilds it from the aggregate's own current records — one
+        # synthetic save per live record, never a replay of deleted or superseded history.
+        def refresh!
+          @projection.reset!
+          @authoritative.all.each do |instance|
+            entry = Persistence::Entry.new(operation: "save", id: instance.id.to_s, state: instance.state.dup)
+            @projection.append(entry)
+            @projection.project(entry)
+          end
+          @projection
+        end
+
         def same_entry?(left, right) = left.operation == right.operation && left.id == right.id && left.state == right.state
 
         def consistent?(entries, present)
@@ -139,18 +104,11 @@ module Hecks
         end
       end
 
-      # The authoritative append-only journal is the durable projection queue.
-      # 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.
+      # The authoritative journal doubles as the queue: entries are committed before a worker
+      # sees them, 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

@@ -6,12 +6,8 @@ require_relative "../../query_specification/common/comparison"
 module Hecks
   module Ports
     module Query
-      # In-memory implementation of a declared query specification:
-      # applies wheres/order_by/offset/limit directly to an Array of
-      # records instead of compiling SQL. Deliberately kept in exact
-      # LIMIT/OFFSET-order agreement with SqlQueryBuilder (see #execute's
-      # own comment) so a query answers the same page regardless of
-      # which adapter backs it.
+      # Applies wheres, order_by, offset and limit to an Array of records, in the same order
+      # as `SqlQueryBuilder` so every adapter answers the same page.
       module InMemory
         FieldPath = QuerySpecification::FieldPath
         Comparison = QuerySpecification::Common::Comparison
@@ -20,17 +16,12 @@ module Hecks
 
         # 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`
+        # @param records [Array<Runtime::Instance, Hash>] the candidates
+        # @param declared [QuerySpecification::Common::Options] provides `wheres`, `order_by`,
+        #   `offset` and `limit`
+        # @param args [Hash{Symbol => Object}] values for Symbol placeholders
+        # @param registry [Runtime::Registry, nil] passed to registry-aware comparisons
+        # @return [Array<Runtime::Instance, Hash>] the matching records, ordered and paged
         def execute(records, declared, args = {}, registry: nil)
           matched = records.select do |record|
             declared.wheres.all? do |clause|
@@ -40,58 +31,19 @@ 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 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
-          # same declaration: `limit 2, offset 1` over three rows is rows
-          # two and three in Postgres and Sqlite, and was row two alone in
-          # memory. Silently — a short page reads exactly like a page that
-          # ran out of rows.
-          #
-          # 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
-          # of a memory-backed query came back empty however many rows
-          # were really there.
+          # Offset before limit, as SQL means `LIMIT n OFFSET m`; the reverse order returns a short
+          # or empty page (`limit 10, offset 10` would drop everything).
           matched = matched.drop(resolve(declared.offset.value, args).to_i) if declared.offset
           matched = matched.first(resolve(declared.limit.value, args).to_i) if declared.limit
           matched
         end
 
-        # The comparator table itself lives in
-        # 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,46 +3,25 @@ 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
-      # 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.
+      # The order an ask answers in: the declared order_by, then identity as a total tiebreaker.
       #
-      # 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.
-      # 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.
+      # An adapter that pushes ordering down must push limit down with it; re-ordering
+      # a page the store already cut yields a top-N of the wrong N.
       module Ordering
         module_function
 
-        # Orders an Array of rows by the declared order, with identity as the total-order
-        # tiebreaker.
+        # Orders rows by `order_by`, breaking ties by `identity`.
         #
-        # @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
+        # @param rows [Array<Object>] the rows to order
+        # @param order_by [QuerySpecification::Common::OrderBy, nil] nil orders by identity alone
+        # @param null_semantics [QuerySpecification::Common::NullSemantics, nil] where nil values
+        #   sort; nil uses the native default
+        # @param identity [Proc] returns a row's comparable identity value
         # @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)
+        # @return [Array<Object>] the ordered rows
         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
-          # would be adding a coin flip of its own.
+          # The index keeps the sort stable; sort_by alone would order tied identities arbitrarily.
           rows = rows.each_with_index.sort_by { |row, index| [identity.call(row), index] }.map(&:first)
           return rows unless order_by
 

data/lib/hecks/ports/query.rb

@@ -1,39 +1,25 @@
 module Hecks
   module Ports
-    # Common query execution boundary. Adapters expose one optional native
-    # hook; all other query behavior remains in the shared interpreter.
-    # Ordering (the meaning of an ask's answer order) and InMemory (the
-    # fallback engine for stores with no query engine of their own) are
-    # its collaborators — query/ordering.rb and query/in_memory.rb.
+    # Query execution boundary: an adapter may expose one native `query` hook, and everything
+    # else runs in the shared interpreter (`query/ordering.rb`, `query/in_memory.rb`).
     module Query
-      # A declared query the chosen adapter cannot honour as written — refused
-      # by `validate!` before the adapter runs it.
+      # A declared query the chosen adapter cannot honour as written.
       class Unsupported < StandardError; end
 
       module_function
 
       # Runs a declared query through the adapter's own `query` hook, if it has one.
       #
-      # A nil answer means "no native engine here", and the caller falls back to the shared
-      # interpreter or to `InMemory.execute`; it never means "no rows", which is `[]`.
+      # nil means "no native engine here" and the caller falls back to `InMemory.execute`; no
+      # rows is `[]`.
       #
-      # @param repository [Persistence::AppendOnly, Object] the repository whose `adapter` is
-      #   asked, or a bare persistence adapter (anything that does not answer `adapter`)
-      # @param specification [QuerySpecification::Common::Options] the declared query: a
-      #   `Bluebook::Query`, a read-model specification, or a delegator wrapping one
-      # @param args [Hash{Symbol => Object}] the caller's arguments, which a where-clause,
-      #   limit or offset written as a Symbol reads its value from
-      # @param context [Hash{Symbol => Object}] passed through to the adapter: `domain:`,
-      #   `aggregate:` and, where a comparator needs one, `registry:`
-      # @return [Array<Runtime::Instance>, nil] the matching records, filtered, ordered and
-      #   paged by the adapter (`[]` when none match); nil if the adapter has no `query`
-      #   method
-      # @raise [Ports::Query::Unsupported] if the specification combines cursor and offset
-      #   pagination, or asks for inspection the adapter cannot provide
-      # @raise [Runtime::WiringError] if a where-clause names an operation no comparator
-      #   handles (raised by the in-memory engine behind `Memory`, `Heki` and the like)
-      # @raise [ArgumentError] if a SQL-backed adapter cannot compile a where-clause's
-      #   operator
+      # @param repository [Persistence::AppendOnly, Object] a repository, or a bare adapter
+      # @param specification [QuerySpecification::Common::Options] the declared query
+      # @param args [Hash{Symbol => Object}] values for Symbol-valued wheres, limit and offset
+      # @param context [Hash{Symbol => Object}] passed to the adapter: `domain:`, `aggregate:`,
+      #   and `registry:` where a comparator needs one
+      # @return [Array<Runtime::Instance>, nil] matches, or nil if the adapter has no `query`
+      # @raise [Ports::Query::Unsupported] see `validate!`
       def execute(repository, specification, args = {}, context: {})
         adapter = repository.respond_to?(:adapter) ? repository.adapter : repository
         return nil unless adapter.respond_to?(:query)
@@ -42,17 +28,8 @@ module Hecks
         adapter.query(specification, args, context: context)
       end
 
-      # Refuses a specification the adapter about to run it cannot honour.
-      #
-      # Inspection is honoured by an adapter with an `inspect_query` method, or, for the
-      # `"sql"` mode alone, by any adapter with a native `query`.
-      #
-      # @param specification [QuerySpecification::Common::Options] the declared query to check
-      # @param adapter [Object] the persistence adapter that would run it; only what it
-      #   responds to (`inspect_query`, `query`) is read
-      # @return [void]
-      # @raise [Ports::Query::Unsupported] if the specification declares both a cursor and
-      #   an offset, or asks for inspection the adapter cannot provide
+      # Refuses cursor with offset pagination, and inspection the adapter cannot provide (`"sql"`
+      # mode needs only a native `query`, other modes an `inspect_query` method).
       def validate!(specification, adapter)
         raise Unsupported, "a query cannot combine cursor and offset pagination" if specification.cursor && specification.offset
 

data/lib/hecks/ports.rb

@@ -1,15 +1,9 @@
 # Hecks::Ports
 #
-# The runtime's named boundaries. Each port is a file beside this one —
-# `ports/persistence.rb`, `ports/query.rb`, … — and a port with supporting
-# cast keeps it in a same-named directory (`ports/persistence/` holds the
-# binding policy, the journal-translation lineage, the repository factory).
-# The `.port` files beside them are the DSL declarations the meta-validator
-# and the Folder adapter load as data.
+# The runtime's named boundaries; each port is a file under `ports/`.
 
 module Hecks
-  # Declared empty here — each `ports/*.rb` file required below reopens it
-  # to add its own port; see the header comment above for what a port is.
+  # The runtime's named boundaries; each port is a file under `ports/`.
   module Ports
   end
 end