hecks 1.0.2 → 1.1.0

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"

data/lib/hecks/projections/ir.rb

@@ -1,6 +1,8 @@
 require_relative "../projector"
 
 module Hecks
+  # Reopened from projections.rb (see there for the namespace's full
+  # rationale) to define and register the :ir target below.
   module Projections
     # The canonical IR, as a constant. The implementation already existed
     # and is already golden-tested (`Projector::IRProjector`, registered

data/lib/hecks/projections/model/deviations.rb

@@ -60,7 +60,8 @@ module Hecks
           "Bluebook"    => { ir_version:     "the EMISSION's own version, not the domain's",
                              canonical_form: "the normalisation table every reader needs beside the IR" },
           "ValueObject" => { closed_set:     "an empty one_of and no one_of are otherwise indistinguishable" },
-          "Aggregate"   => { ports:          "declared in the hecksagon, attached after the aggregate exists" }
+          "Aggregate"   => { ports:          "declared in the hecksagon, attached after the aggregate exists" },
+          "Policy"      => { where_ast:      "the structured form of `where`, derived from the same text at emission" }
         }.freeze
 
         # DECLARED, AND DELIBERATELY NOT EMITTED. The category that had no

data/lib/hecks/projections/model.rb

@@ -50,7 +50,11 @@ module Hecks
           # a binding that reads an event field and one that supplies a
           # literal string are otherwise indistinguishable once written
           # down (see `MetaValidator::Readings`' own note on exactly that).
-          renders:   { with_spec: "-> { with_spec.map { |key, value| [key.to_s, Bluebook.render_value(value)] } }" },
+          renders:   { with_spec: "-> { with_spec.map { |key, value| [key.to_s, Bluebook.render_value(value)] } }",
+                       # COMPUTED (Deviations::COMPUTED["Policy"]): the structured
+                       # form of `where`, a pure function of that text, the same
+                       # `ast` every rule row carries beside its `canonical`.
+                       where_ast: "-> { where_ast }" },
           settles:   false
         }
       }.freeze
@@ -66,7 +70,7 @@ module Hecks
           # GENERATED — projected from the language's own #{name} aggregate.
           # DO NOT EDIT: the holding half is rendered, and #{host.fetch(:behaviour)}
           # is where anything hand-written belongs.
-          require_relative "behaviour/#{File.basename(host.fetch(:file), ".rb")}"
+          require_relative "behaviour/#{File.basename(host.fetch(:file), '.rb')}"
 
           module Hecks
             module Bluebook
@@ -87,14 +91,15 @@ module Hecks
 
       # The emission, keyed as the model spells it and sourced as the
       # language declares it.
+      # A COMPUTED field (Deviations::COMPUTED) is emitted too — it is
+      # model-only by definition, so it rides after the declared fields
+      # and MUST have a `renders` entry, there being nothing to `send`.
       def emits(bluebook, name)
-        fields  = emitted_fields(bluebook, name)
+        fields  = emitted_fields(bluebook, name) + Deviations.computed(name)
         renders = HOST.fetch(name).fetch(:renders, {})
         width   = fields.map { |f| f.to_s.length }.max.to_i
 
-        "emits_ir(\n" +
-          fields.map { |f| "  #{"#{f}:".ljust(width + 1)} #{renders.fetch(f, ":#{f}")}" }.join(",\n") +
-          "\n)"
+        "emits_ir(\n#{fields.map { |f| "  #{"#{f}:".ljust(width + 1)} #{renders.fetch(f, ":#{f}")}" }.join(",\n")}\n)"
       end
 
       # WHAT THE CONSTRUCT EMITS: what the language declares, less every
@@ -121,18 +126,18 @@ module Hecks
         # here rather than typed in — a comment that survives
         # regeneration is one the generator writes.
         reasons = Deviations::OFF_THE_WIRE.fetch(host.fetch(:construct, ""), {})
-        (lines + accessors.map { |a|
+        (lines + accessors.map do |a|
           why = reasons[a]
           (why ? "\n# #{a.upcase}, DECLARED AND DELIBERATELY OFF THE WIRE\n# #{wrap(why)}\n" : "") +
             "attr_accessor :#{a}"
-        }).join("\n")
+        end).join("\n")
       end
 
       def constructor(host)
         args = host.fetch(:defaults).map { |f, d| d ? "#{f}: #{d}" : "#{f}:" }.join(", ")
-        body = host.fetch(:defaults).keys.map { |f|
+        body = host.fetch(:defaults).keys.map do |f|
           "  @#{f} = #{f}#{host.fetch(:coerce, {})[f]}"
-        }
+        end
         body << "\n  settle" if host.fetch(:settles, true)
 
         "def initialize(#{args})\n#{body.join("\n")}\nend"

data/lib/hecks/projections/vocabulary.rb

@@ -58,9 +58,7 @@ module Hecks
 
       def render(bluebook)
         rows = tables(bluebook).sort_by(&:first).map do |name, members|
-          "      #{name.inspect} => [\n" +
-            members.map { |row| "        #{row.inspect}.freeze" }.join(",\n") +
-            "\n      ].freeze"
+          "      #{name.inspect} => [\n#{members.map { |row| "        #{row.inspect}.freeze" }.join(",\n")}\n      ].freeze"
         end
 
         <<~RUBY

data/lib/hecks/projector/cli_projector.rb

@@ -54,12 +54,12 @@ module Hecks
           aggregate.queries.each  { |q| claim(questions, name_for(aggregate, q), query_spec(bluebook, aggregate, nil, q)) }
 
           aggregate.entities.each do |entity|
-            entity.commands.each { |c|
+            entity.commands.each do |c|
               claim(verbs, name_for(aggregate, c, entity), command_spec(bluebook, aggregate, entity, c))
-            }
-            entity.queries.each { |q|
+            end
+            entity.queries.each do |q|
               claim(questions, name_for(aggregate, q, entity), query_spec(bluebook, aggregate, entity, q))
-            }
+            end
           end
 
           # A PORT IS A VERB TOO, and leaving it off the map was a real gap
@@ -235,7 +235,11 @@ module Hecks
           # `CommandInterpreter`/`EntityInterpreter` call it, never the port
           # dispatch path), so `role_gated: false` always, unlike
           # `command_spec` where the same key name means a real one.
-          role: operation.outbound? ? "#{aggregate.hecks_name} asking #{port.name}" : "#{port.name} telling #{aggregate.hecks_name}",
+          role: if operation.outbound?
+                  "#{aggregate.hecks_name} asking #{port.name}"
+                else
+                  "#{port.name} telling #{aggregate.hecks_name}"
+                end,
           role_gated: false,
           summary: port_summary(port, operation), arguments: arguments }
       end
@@ -289,8 +293,8 @@ module Hecks
       # malformed records into a real store, which is what it did on its first
       # run against the pizzas database.
       def options_for(attribute, holder, aggregate, prefix = nil, optional = nil)
-        path     = [prefix, attribute.name].compact.join(".")
-        optional = optional || attribute.optional?
+        path = [prefix, attribute.name].compact.join(".")
+        optional ||= attribute.optional?
         return [reference_option(attribute)] if attribute.reference?
 
         value_object = value_object_for(attribute, holder, aggregate)
@@ -408,38 +412,54 @@ module Hecks
         text.to_s.split(/(?<=\.)\s/).first.to_s
       end
 
+      # FOUR TEXT BLOCKS, IN FIXED DISPLAY ORDER — meta (name/kind/role),
+      # invocation, arguments, refusals. Each block is independent of the
+      # others' content (only the OUTPUT ORDER is fixed, and stays fixed
+      # below), so each is its own method returning the lines it
+      # contributes — `[]` when it contributes none — concatenated in the
+      # same order the original inline version built them in.
       def verb_help(program, name, spec, ask: false)
+        out = verb_help_meta_lines(name, spec)
+        out.concat(verb_help_invocation_lines(program, name, spec, ask))
+        out.concat(verb_help_argument_lines(spec))
+        out.concat(verb_help_refusal_lines(spec))
+        out.join("\n")
+      end
+
+      def verb_help_meta_lines(name, spec)
         out = ["#{name} — #{spec[:summary]}", ""]
         out << "dispatches #{spec[:verb]}" if spec[:kind] == :command
         out << "reads #{spec[:verb]}"      if spec[:kind] == :query
         out << "issued by #{spec[:role]}"  if spec[:role]
-        out << ""
+        out
+      end
+
+      def verb_help_invocation_lines(program, name, spec, ask)
         invocation = ask ? "#{program} ask #{name}" : "#{program} #{name}"
-        out << "  #{invocation}#{spec[:arguments].map { |a| " #{a[:path]}=…" }.join}"
-        out << ""
+        ["", "  #{invocation}#{spec[:arguments].map { |a| " #{a[:path]}=…" }.join}", ""]
+      end
 
-        unless spec[:arguments].empty?
-          width = spec[:arguments].map { |a| a[:path].length }.max
-          spec[:arguments].each do |argument|
-            notes = []
-            notes << argument[:type]
-            notes << "one of #{argument[:enum].join(', ')}" if argument[:enum]
-            notes << "matches #{argument[:pattern]}"        if argument[:pattern]
-            notes << "defaults to #{argument[:default].inspect}" unless argument[:default].nil?
-            notes << argument[:note]                        if argument[:note]
-            notes << "optional"                             unless argument[:required]
-            out << "  #{argument[:path].ljust(width)}  #{notes.join('; ')}"
-          end
-          out << ""
+      def verb_help_argument_lines(spec)
+        return [] if spec[:arguments].empty?
+
+        width = spec[:arguments].map { |a| a[:path].length }.max
+        lines = spec[:arguments].map do |argument|
+          notes = []
+          notes << argument[:type]
+          notes << "one of #{argument[:enum].join(', ')}" if argument[:enum]
+          notes << "matches #{argument[:pattern]}"        if argument[:pattern]
+          notes << "defaults to #{argument[:default].inspect}" unless argument[:default].nil?
+          notes << argument[:note]                        if argument[:note]
+          notes << "optional"                             unless argument[:required]
+          "  #{argument[:path].ljust(width)}  #{notes.join('; ')}"
         end
+        lines << ""
+      end
 
-        unless Array(spec[:refusals]).empty?
-          out << "refused when:"
-          spec[:refusals].each { |refusal| out << "  #{refusal}" }
-          out << ""
-        end
+      def verb_help_refusal_lines(spec)
+        return [] if Array(spec[:refusals]).empty?
 
-        out.join("\n")
+        ["refused when:", *spec[:refusals].map { |refusal| "  #{refusal}" }, ""]
       end
     end
   end

data/lib/hecks/projector/docs_projector.rb

@@ -52,7 +52,7 @@ module Hecks
         out << chapter_header(bluebook, depth) unless only
         Array(aggregates(bluebook, only)).each { |aggregate| out << aggregate_section(aggregate, only ? depth : depth + 1) }
         out << closing(bluebook, depth + 1) unless only
-        out.compact.join("\n").rstrip + "\n"
+        "#{out.compact.join("\n").rstrip}\n"
       end
 
       # A NAME THAT NAMES NOTHING IS REFUSED, not answered with an empty
@@ -179,7 +179,7 @@ module Hecks
         value_object = value_object_for(attribute, holder)
         inner =
           if value_object
-            "{ " + value_object.attributes.map { |f| "#{f.name}: #{f.type}" }.join(", ") + " }"
+            "{ #{value_object.attributes.map { |f| "#{f.name}: #{f.type}" }.join(', ')} }"
           else
             attribute.type.to_s
           end
@@ -244,19 +244,13 @@ module Hecks
       end
 
       def command_entry(command, holder, depth)
-        out = [h(depth, "#{command.hecks_name}#{command.creates? ? ' *(creates)*' : ''}"), ""]
+        out = [h(depth, "#{command.hecks_name}#{' *(creates)*' if command.creates?}"), ""]
         out += [command.goal, ""] if command.goal
         out << "Issued by: **#{command.role}**." if command.role
         out << ""
 
         arguments = command.attributes
-        unless arguments.empty?
-          rows = arguments.map do |attribute|
-            shape = attribute.reference? ? "id of a `#{attribute.type.target_name}`" : shape_of(attribute, holder)
-            ["`#{attribute.name}`", shape, attribute.optional? ? "" : "required"]
-          end
-          out << table(%w[argument shape needed], rows)
-        end
+        out << table(%w[argument shape needed], command_argument_rows(arguments, holder)) unless arguments.empty?
 
         refusals = refusals_of(command, holder)
         unless refusals.empty?
@@ -272,6 +266,17 @@ module Hecks
         out.join("\n")
       end
 
+      # The argument table's own rows — a pure per-attribute mapping with
+      # nothing to share with `command_entry`'s other sections, extracted
+      # only to keep that method to the one shape every section there
+      # follows: build a chunk, append it if non-empty.
+      def command_argument_rows(arguments, holder)
+        arguments.map do |attribute|
+          shape = attribute.reference? ? "id of a `#{attribute.type.target_name}`" : shape_of(attribute, holder)
+          ["`#{attribute.name}`", shape, attribute.optional? ? "" : "required"]
+        end
+      end
+
       # EVERY WAY THIS VERB CAN SAY NO, gathered from the three places a
       # chapter states them — the lifecycle it is an edge of, its own
       # `given`s, and the fact that a reference has to resolve. A caller
@@ -284,7 +289,11 @@ module Hecks
         froms = lifecycle && lifecycle.transitions.filter_map do |name, transition|
           Array(transition.from) if name.to_s == command.hecks_name
         end.flatten.uniq
-        refusals << "`#{lifecycle.field}` is anything other than #{froms.map { |f| "`#{f}`" }.join(' or ')}" if froms && !froms.empty?
+        if froms && !froms.empty?
+          refusals << "`#{lifecycle.field}` is anything other than #{froms.map do |f|
+            "`#{f}`"
+          end.join(' or ')}"
+        end
 
         command.attributes.select(&:reference?).each do |reference|
           refusals << "no `#{reference.type.target_name}` exists for the id given as `#{reference.name}`"
@@ -302,7 +311,7 @@ module Hecks
         queries.each do |query|
           shape   = query.to_h
           takes   = Array(shape[:attributes]).map { |a| "`#{a[:name]}`" }.join(", ")
-          out << "**#{query.hecks_name}**#{takes.empty? ? '' : " (#{takes})"}  "
+          out << "**#{query.hecks_name}**#{" (#{takes})" unless takes.empty?}  "
           out << (query.description ? "#{query.description}  " : "")
           filters = Array(shape[:wheres]).map { |w| "`#{w[:field]} #{w[:op]} #{w[:value].inspect}`" }
           out << "Filters: #{filters.join(', ')}." unless filters.empty?

data/lib/hecks/projector/exporter.rb

@@ -3,6 +3,13 @@ require_relative "../ports/persistence"
 
 module Hecks
   module Projector
+    # Registry-wide serialization to Hash/JSON: bluebook IR
+    # (`call`/`json`), era-adapter lineage-capability flags (`lineage`),
+    # and translation edges in both their DIGEST-relevant declared shape
+    # (`translation_hash`, what ApprovalDigest hashes) and their
+    # consumer-ready COMPILED shape with precompiled SQL attached
+    # (`translations`/`compiled_translation_aggregate`). Read directly by
+    # bin/ir, bin/project_rust, and the translation/audit approval digest.
     module Exporter
       module_function
 
@@ -150,7 +157,9 @@ module Hecks
 
         translation_aggregate(aggregate).merge(
           compiled_state_expression: Translation::RuleCompiler.compile_rules(aggregate),
-          compiled_id_expression:    Translation::RuleCompiler.rekeyed?(aggregate) ? Translation::RuleCompiler.compile_id_expression(aggregate) : nil
+          compiled_id_expression:    (if Translation::RuleCompiler.rekeyed?(aggregate)
+                                        Translation::RuleCompiler.compile_id_expression(aggregate)
+                                      end)
         )
       end
     end