hecks 1.0.2 → 1.2.0

data/lib/hecks/ports/persistence/plugins/era/translation/audit/layer_two.rb

@@ -24,6 +24,26 @@ module Hecks
         def layer_two!(violations, aggregate, declared, before, after)
           rekeyed = declared && !declared.rekeys.empty?
 
+          check_id_conservation!(violations, aggregate, before, after, rekeyed: rekeyed)
+
+          return unless declared
+          # No correspondence between an old id and its rekeyed row exists
+          # in Ruby (the rekey's SQL is its only implementation, same as
+          # compute's) — exempt from the per-record equivalence gate for
+          # the same reason compute paths already are, extended to the
+          # whole record since an old-id lookup into `after` can never
+          # succeed once the id itself has changed.
+          return if rekeyed
+
+          check_value_preservation!(violations, aggregate, declared, before, after)
+        end
+
+        # Record-count / id-set conservation — one of the two properties
+        # this module's own header names, and independent of the other
+        # (per-rule value preservation, below): it needs only `before`,
+        # `after`, and whether the edge rekeyed, never the declared rules
+        # themselves.
+        def check_id_conservation!(violations, aggregate, before, after, rekeyed:)
           # A rekey legitimately changes the id SET (that's the entire
           # point) — set-equality would flag every honest rekey as data
           # loss. What must still hold is RECORD COUNT: a botched rekey
@@ -43,15 +63,13 @@ module Hecks
             violations << "#{aggregate.name}: the id set changed across the edge " \
                           "(lost #{lost.sort.inspect}, gained #{gained.sort.inspect})"
           end
-          return unless declared
-          # No correspondence between an old id and its rekeyed row exists
-          # in Ruby (the rekey's SQL is its only implementation, same as
-          # compute's) — exempt from the per-record equivalence gate for
-          # the same reason compute paths already are, extended to the
-          # whole record since an old-id lookup into `after` can never
-          # succeed once the id itself has changed.
-          return if rekeyed
+        end
 
+        # Per-rule value preservation — the other property this module's
+        # header names. Only reached once `layer_two!` has already ruled
+        # out "no declared edge" and "rekeyed" (see its own comment on
+        # that second guard); this method assumes both are false.
+        def check_value_preservation!(violations, aggregate, declared, before, after)
           rules = Ports::Persistence::Lineage.from_declared(declared, aggregate.name)
           compute_paths = declared.computes.flat_map { |compute| [compute.from, compute.to] }.map(&:to_s)
 
@@ -63,7 +81,7 @@ module Hecks
             actual = strip_compute_paths(normalize(after[id]), compute_paths)
             next if expected == actual
 
-            diverged = (expected.keys | actual.keys).select { |key| expected[key] != actual[key] }
+            diverged = (expected.keys | actual.keys).reject { |key| expected[key] == actual[key] }
             violations << "#{aggregate.name}##{id}: the translated state diverges from the reference " \
                           "transform at #{diverged.sort.join(', ')}"
           end

data/lib/hecks/ports/persistence/plugins/era/translation/audit/unfed_report.rb

@@ -7,6 +7,15 @@ module Hecks
       # attribute, and the loud refusal for a REQUIRED one comes from
       # Layer 1 the moment an invariant reads it.
       module UnfedReport
+        # `fed` build-up plus one ordered guard chain per attribute
+        # (already fed, has a default, actually present in some record, no
+        # records to check at all) answering a single question — "is
+        # anything, ever, going to feed this field" — where each `next`
+        # rules out one way the answer is "not unfed after all" before the
+        # next is even worth asking. Splitting the guards out would just
+        # turn each into a same-shaped one-line predicate call.
+        # rubocop:disable-next Metrics/CyclomaticComplexity
+        # rubocop:disable-next Metrics/PerceivedComplexity
         def unfed(aggregate, declared, after)
           fed = if declared
                   (declared.renames.values.map(&:to_s) +

data/lib/hecks/ports/persistence/plugins/era/translation/scaffold/differ.rb

@@ -74,27 +74,43 @@ module Hecks
           held_attrs = (held_shape["attributes"] || []).to_h { |attribute| [attribute["name"], attribute] }
           current_attrs = (current_shape["attributes"] || []).to_h { |attribute| [attribute["name"], attribute] }
 
-          # retype pass: same attribute name, same member structure, the
-          # TYPE's own name changed
-          (held_attrs.keys & current_attrs.keys).each do |name|
+          rules.concat(retype_rules(held_attrs, current_attrs))
+          retyped = rules.filter_map { |rule| rule[:from] if rule[:kind] == :retype }
+
+          vanished = vanished_paths(held_attrs, current_attrs, retyped)
+          appeared = appeared_paths(held_attrs, current_attrs, retyped)
+
+          # Mutates `rules` in place (not build-and-concat, like the two
+          # passes above) because it must READ its own earlier writes:
+          # `taken`, below, is recomputed from `rules` at the top of every
+          # iteration, so a target this same loop already claimed for an
+          # earlier vanished path is excluded from a later one. Passing a
+          # snapshot instead of the live array would let two vanished
+          # paths both match the same appeared target.
+          resolve_vanished_rules!(rules, vanished, appeared)
+          rules
+        end
+
+        # retype pass: same attribute name, same member structure, the
+        # TYPE's own name changed
+        def retype_rules(held_attrs, current_attrs)
+          (held_attrs.keys & current_attrs.keys).filter_map do |name|
             held = held_attrs[name]
             current = current_attrs[name]
             next if held == current
             next unless container?(held) && container?(current)
             next unless held["type"]["members"] == current["type"]["members"] && held["list"] == current["list"]
 
-            rules << { kind: :retype, from: held["type"]["type"], to: current["type"]["type"] }
+            { kind: :retype, from: held["type"]["type"], to: current["type"]["type"] }
           end
-          retyped = rules.filter_map { |rule| rule[:from] if rule[:kind] == :retype }
-
-          vanished = vanished_paths(held_attrs, current_attrs, retyped)
-          appeared = appeared_paths(held_attrs, current_attrs, retyped)
+        end
 
+        def resolve_vanished_rules!(rules, vanished, appeared)
           vanished.each do |path, signature|
             matches = appeared.select { |_, candidate| candidate == signature }.keys
             taken = rules.filter_map { |rule| rule[:to] if %i[rename move].include?(rule[:kind]) }
             matches -= taken
-            if matches.size == 1 && vanished.count { |_, other| other == signature } == 1
+            if matches.size == 1 && vanished.one? { |_, other| other == signature }
               target = matches.first
               kind = path.include?(".") || target.include?(".") ? :move : :rename
               rules << { kind: kind, from: path, to: target }
@@ -103,7 +119,6 @@ module Hecks
               rules << { kind: :unresolved, from: path, candidates: candidates }
             end
           end
-          rules
         end
 
         # Held paths that need explaining: whole attributes that vanished,

data/lib/hecks/ports/persistence/plugins/era/translation/scaffold/renderer.rb

@@ -10,12 +10,8 @@ module Hecks
           edge.aggregates.each do |aggregate|
             header = "  aggregate #{aggregate.name.inspect}"
             header += ", was: #{aggregate.was.inspect}" if aggregate.was
-            if aggregate.rules.empty?
-              lines << "#{header} do"
-            else
-              lines << "#{header} do"
-              aggregate.rules.each { |rule| lines << "    #{render_rule(rule)}" }
-            end
+            lines << "#{header} do"
+            aggregate.rules.each { |rule| lines << "    #{render_rule(rule)}" } unless aggregate.rules.empty?
             lines << "  end"
           end
           edge.retired.each { |name| lines << "  retired #{name.inspect}" }

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

@@ -35,7 +35,9 @@ module Hecks
           # unchanged: registered only when this registry has an aggregate
           # actually bound to a lineage-capable adapter.
           def contribute_boot_gates(registry, gates)
-            gates.register(:era_compute_rules, ->(reg, _dir) { Runtime::EraCheck.check_compute_rules_for_registry!(reg) }, phase: :pre_verify)
+            gates.register(:era_compute_rules, lambda { |reg, _dir|
+              Runtime::EraCheck.check_compute_rules_for_registry!(reg)
+            }, phase: :pre_verify)
             gates.register(:era_check, Runtime::EraCheck.method(:check_lineage!), phase: :pre_verify) if
               Runtime::EraCheck.lineage_capable_registry?(registry)
           end

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

@@ -33,7 +33,7 @@ module Hecks
                 "#{self.class.name} is a remote-runtime delegate — dispatch through " \
                 "Runtime::RemoteDispatcher instead of writing through the repository directly"
         end
-        alias_method :project, :append
+        alias project append
 
         def entries = []
       end

data/lib/hecks/ports/persistence.rb

@@ -1,9 +1,9 @@
 module Hecks
   module Ports
     module Persistence
-      NAME = "persistence"
-      VERB = "persisted_by"
-      DEFAULT_ADAPTER = "Memory"
+      NAME = "persistence".freeze
+      VERB = "persisted_by".freeze
+      DEFAULT_ADAPTER = "Memory".freeze
     end
   end
 end
@@ -18,6 +18,10 @@ require_relative "persistence/null_saga_store"
 
 module Hecks
   module Ports
+    # Reopened once `BindingPolicy`/`RepositoryFactory` (required above) are
+    # loaded, to add the persistence port's actual call surface: resolving
+    # which adapter authoritatively binds an aggregate and building the
+    # repository that reads/writes it.
     module Persistence
       module_function
 

data/lib/hecks/ports/projection.rb

@@ -7,8 +7,8 @@ module Hecks
     # Projection is a read-side port. Its stores are rebuildable consumers of
     # authoritative entries and never participate in command decisions.
     module Projection
-      NAME = "projection"
-      VERB = "projected_by"
+      NAME = "projection".freeze
+      VERB = "projected_by".freeze
 
       module_function
 
@@ -26,6 +26,11 @@ 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.
       class Worker
         attr_reader :projection
 
@@ -67,7 +72,10 @@ module Hecks
           unless consistent?(entries, present)
             raise Runtime::WiringError, "projection history does not match its authoritative history" if @policy == :strict
           end
-          entries.drop(present.length).each { |entry| @projection.append(entry); @projection.project(entry) }
+          entries.drop(present.length).each do |entry|
+            @projection.append(entry)
+            @projection.project(entry)
+          end
           @projection
         end
 
@@ -78,9 +86,9 @@ module Hecks
         def same_entry?(left, right) = left.operation == right.operation && left.id == right.id && left.state == right.state
 
         def consistent?(entries, present)
-          present.length <= entries.length && entries.first(present.length).zip(present).all? { |left, right|
+          present.length <= entries.length && entries.first(present.length).zip(present).all? do |left, right|
             same_entry?(left, right)
-          }
+          end
         end
       end
 

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

@@ -6,6 +6,12 @@ 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.
       module InMemory
         FieldPath = QuerySpecification::FieldPath
         Comparison = QuerySpecification::Common::Comparison
@@ -14,9 +20,9 @@ module Hecks
 
         def execute(records, declared, args = {}, registry: nil)
           matched = records.select do |record|
-            declared.wheres.all? { |clause|
+            declared.wheres.all? do |clause|
               holds?(clause, comparable(FieldPath.dig(record, clause.field)), args, registry: registry)
-            }
+            end
           end
           field   = declared.order_by&.field
           matched = Ordering.apply(matched, declared.order_by, declared.null_semantics,

data/lib/hecks/ports/query.rb

@@ -19,9 +19,7 @@ module Hecks
       end
 
       def validate!(specification, adapter)
-        if specification.cursor && specification.offset
-          raise Unsupported, "a query cannot combine cursor and offset pagination"
-        end
+        raise Unsupported, "a query cannot combine cursor and offset pagination" if specification.cursor && specification.offset
 
         return if specification.inspection.nil? || adapter.respond_to?(:inspect_query)
         return if specification.inspection.mode.to_s == "sql" && adapter.respond_to?(:query)

data/lib/hecks/ports.rb

@@ -8,6 +8,8 @@
 # and the Folder adapter load as data.
 
 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.
   module Ports
   end
 end

data/lib/hecks/projections/diagrams.rb

@@ -448,9 +448,17 @@ module Hecks
       # single source at all — its own field NAMES are the fact worth
       # stating (real: `Order.AddTopping` appends `name, amount`).
       def surface_diagram(bluebook, holder)
-        lines = holder.commands.map { |command| "    #{holder.hecks_name}[(#{holder.hecks_name})] -->|does| #{command_node(holder.hecks_name, command.hecks_name)}" }
-        lines += holder.commands.flat_map { |command| command.mutations.map { |mutation| mutation_edge(holder, command, mutation) } }
-        lines += holder.queries.map { |query| "    #{holder.hecks_name}[(#{holder.hecks_name})] -.->|asks| #{query_node(holder.hecks_name, query.hecks_name)}" }
+        lines = holder.commands.map do |command|
+          "    #{holder.hecks_name}[(#{holder.hecks_name})] -->|does| #{command_node(holder.hecks_name, command.hecks_name)}"
+        end
+        lines += holder.commands.flat_map do |command|
+          command.mutations.map do |mutation|
+            mutation_edge(holder, command, mutation)
+          end
+        end
+        lines += holder.queries.map do |query|
+          "    #{holder.hecks_name}[(#{holder.hecks_name})] -.->|asks| #{query_node(holder.hecks_name, query.hecks_name)}"
+        end
 
         subject = "#{holder.hecks_name}'s own declared commands (and what each writes) and queries"
         "#{header(bluebook.name, subject)}flowchart LR\n#{lines.uniq.join("\n")}\n"