hecks 2.9.0 → 3.0.1

data/rust/project/read_models.rb

@@ -0,0 +1,690 @@
+require_relative "skip_reason"
+
+# Compiles declared read models into the static Rust tables
+# `kernel/read_model.rs` interprets at runtime.
+module RustProjection
+  module Projector
+    module_function
+
+    # `group_by` is now always present on the wire (`[]` when undeclared), so
+    # eligibility below must check its value, not the key's mere presence.
+    READ_MODEL_BARE_KEYS = %i[name description reference_name reference_target query_name aggregate_heads
+                              wheres order_by offset limit freshness index_hints group_by null_semantics
+                              authorization count median_field sum_field avg_field min_field max_field
+                              percentile_field percentile_at any_field all_field].freeze
+
+    # Returns nil if the read model can be generated as-is, otherwise a
+    # short reason string naming what's unsupported.
+    def read_model_skip_reason(read_model, aggregates_by_name, unsupported_names)
+      extra = read_model.keys.map(&:to_sym) - READ_MODEL_BARE_KEYS
+      return read_model_options_skip_reason(extra) if extra.any?
+
+      # Checked before the root lookup below: a rootless, group_by'd read
+      # model has no reference_target, and reporting that as "no matching
+      # aggregate head" would be misleading instead of the real reason.
+      return group_by_skip_reason(read_model, aggregates_by_name, unsupported_names) if Array(read_model[:group_by]).any?
+
+      heads = read_model[:aggregate_heads]
+      root = heads.find { |head| head[:aggregate].to_s == read_model[:reference_target].to_s }
+      # A rootless read model (every head reads its own whole table) has no
+      # reference_target at all; only a named target with no matching head,
+      # which leaves nothing for the root fetch to key off, is refused.
+      if !root && !read_model[:reference_target].to_s.empty?
+        return skip("missing_root_head", "declares reference_to #{read_model[:reference_target]}, but includes no matching aggregate head — " \
+                                         "nothing for this generator's own root fetch to key off")
+      end
+
+      if root && !aggregates_by_name[root[:aggregate]] && nested_entity_names(aggregates_by_name).include?(root[:aggregate].to_s)
+        return entity_head_skip_reason(root[:aggregate], "root", "fetch by id")
+      end
+
+      heads.each do |head|
+        reason = read_model_head_skip_reason(head, aggregates_by_name, unsupported_names)
+        return reason if reason
+      end
+
+      reason = read_model_options_content_skip_reason(read_model, aggregates_by_name)
+      return reason if reason
+
+      aggregation_skip_reason(read_model, aggregates_by_name)
+    end
+
+    def read_model_options_skip_reason(extra)
+      skip(extra.map(&:to_s).min, "declares #{extra.map(&:to_s).sort.join(', ')} — out of scope for this generator: cursor/" \
+        "consistency/inspection are real " \
+        "capabilities Ports::Query::InMemory/Ports::Query::Ordering/TenantScope implement that this generator " \
+        "does not port (this file's own header has the full argument, the same boundary queries.rb already " \
+        "draws for a declared AGGREGATE query); freshness/use_index are never disqualifying on their own — " \
+        "neither is read by the in-memory interpreter path this kernel matches")
+    end
+
+    # The many-side heads a where/order_by/offset/limit's own `on:` (or, for an
+    # untargeted option, the sole many-side head) could possibly name — every
+    # many-side head this read model declares.
+    def read_model_many_heads(read_model)
+      read_model[:aggregate_heads].select { |head| head[:many] }
+    end
+
+    # Whether one declared option (its own `:target`, or nil when untargeted)
+    # applies to `head`. `target` names the included aggregate by TYPE (ADR
+    # 0055), not by its `as:` alias; nil only ever means "the sole many-side
+    # head" — `ReadModelBuilder#seal_query_options` refuses an untargeted
+    # option whenever a read model declares more than one, so an untargeted
+    # option reaching codegen at all is proof there's exactly one to mean.
+    def option_target_matches_head?(target, head, many_heads)
+      return many_heads.size == 1 && many_heads.first[:as].to_s == head[:as].to_s if target.nil?
+
+      target.to_s == head[:aggregate].to_s
+    end
+
+    # Whether `head` has at least one declared where/order_by/offset/limit
+    # (or, for the sole many-side head only, a declared `authorize ...,
+    # tenant:` — `on:` doesn't extend to `tenant:`, a deliberate ADR 0055
+    # scope limit) targeting it.
+    def read_model_option_targets_head?(read_model, head, many_heads)
+      Array(read_model[:wheres]).any? { |w| option_target_matches_head?(w[:target], head, many_heads) } ||
+        (read_model[:order_by] && option_target_matches_head?(read_model[:order_by][:target], head, many_heads)) ||
+        (read_model[:limit] && option_target_matches_head?(read_model[:limit][:target], head, many_heads)) ||
+        (read_model[:offset] && option_target_matches_head?(read_model[:offset][:target], head, many_heads)) ||
+        (read_model.dig(:authorization, :tenant) && many_heads.size == 1 && many_heads.first[:as].to_s == head[:as].to_s)
+    end
+
+    # Every many-side head this read model declares options for, in
+    # aggregate_heads' own declared order (stable regardless of where in the
+    # block a `where`/`order_by`/`on:` appears) — one entry when there's a
+    # single many-side head (the pre-ADR-0055 shape), more than one only when
+    # `on:` targets several.
+    def read_model_filtered_heads(read_model)
+      many_heads = read_model_many_heads(read_model)
+      many_heads.select { |head| read_model_option_targets_head?(read_model, head, many_heads) }
+    end
+
+    # One targeted head's own where/order_by/offset/limit, pulled out of the
+    # read model's full declared set. `authorization` carries `read_model`'s
+    # own declared authorization only for the sole many-side head (`on:`
+    # doesn't extend to `tenant:`), nil for every other targeted head.
+    def read_model_head_query(read_model, head, many_heads)
+      {
+        wheres: Array(read_model[:wheres]).select { |w| option_target_matches_head?(w[:target], head, many_heads) },
+        order_by: read_model[:order_by] && option_target_matches_head?(read_model[:order_by][:target], head, many_heads) ? read_model[:order_by] : nil,
+        limit: read_model[:limit] && option_target_matches_head?(read_model[:limit][:target], head, many_heads) ? read_model[:limit] : nil,
+        offset: read_model[:offset] && option_target_matches_head?(read_model[:offset][:target], head, many_heads) ? read_model[:offset] : nil,
+        authorization: many_heads.size == 1 && many_heads.first[:as].to_s == head[:as].to_s ? read_model[:authorization] : nil,
+      }
+    end
+
+    # Checks every targeted head's own where/order_by/limit for generability
+    # against ITS aggregate (not the read model's root); nil means clean.
+    def read_model_options_content_skip_reason(read_model, aggregates_by_name)
+      many_heads = read_model_many_heads(read_model)
+
+      read_model_filtered_heads(read_model).each do |head|
+        aggregate = aggregates_by_name[head[:aggregate]]
+        return entity_head_skip_reason(head[:aggregate], "filtered head", "filter, order or authorize") unless aggregate
+
+        value_objects_by_name = aggregate[:value_objects].to_h { |vo| [vo[:name], vo] }
+        head_query = read_model_head_query(read_model, head, many_heads)
+        head_label = "head #{head[:aggregate]} (as #{head[:as]})"
+
+        head_query[:wheres].each do |where|
+          field = where[:field].to_s
+          hop = query_hop_plan(aggregate, field, aggregates_by_name)
+          if hop.nil? && field.include?("/")
+            return skip("reference_hop_where", "#{head_label}'s own where clause on #{field.inspect} hops through a " \
+                   "reference this generator can't resolve yet (more than one hop, the head isn't a real " \
+                   "reference attribute, or the target aggregate isn't declared in this domain) — not generated yet")
+          end
+
+          if hop
+            target_value_objects_by_name = hop[:target][:value_objects].to_h { |vo| [vo[:name], vo] }
+            reason = query_where_skip_reason(where.merge(field: hop[:inner_field]), hop[:target], target_value_objects_by_name)
+            return reskip(reason, "#{head_label}'s own hop through #{hop[:via_field]} to " \
+                   "#{hop[:target_aggregate]}'s own #{reason}") if reason
+            next
+          end
+
+          reason = query_where_skip_reason(where, aggregate, value_objects_by_name)
+          return reskip(reason, "#{head_label}'s own #{reason}") if reason
+        end
+
+        auth_reason = declared_authorization_skip_reason(head_query[:authorization], aggregate, value_objects_by_name)
+        return auth_reason if auth_reason
+
+        order_reason = declared_order_by_skip_reason(head_query[:order_by], aggregate, value_objects_by_name)
+        return order_reason if order_reason
+
+        offset_reason = declared_offset_skip_reason(head_query[:offset])
+        return offset_reason if offset_reason
+
+        limit_reason = declared_limit_skip_reason(head_query[:limit])
+        return limit_reason if limit_reason
+      end
+
+      nil
+    end
+
+    # Every reduction beyond `count` (which needs no field), each mapped to whether it admits
+    # only Integer (not Float) or a boolean field — mirrors
+    # Runtime::ReadModelInterpreter::INTEGER_ONLY_REDUCTIONS/BOOLEAN_REDUCTIONS (ADR 0078).
+    AGGREGATION_FIELD_KEYS = %i[median_field sum_field avg_field min_field max_field percentile_field
+                                any_field all_field].freeze
+    INTEGER_ONLY_AGGREGATION_FIELDS = %i[sum_field avg_field].freeze
+    BOOLEAN_AGGREGATION_FIELDS = %i[any_field all_field].freeze
+
+    # A reduction field's own eligibility, checked after where/order_by/limit since a
+    # reduction only reduces the already-filtered row set.
+    def aggregation_skip_reason(read_model, aggregates_by_name)
+      field_key = AGGREGATION_FIELD_KEYS.find { |key| read_model[key] }
+      return nil unless field_key
+
+      target = read_model[:aggregate_heads].find { |head| head[:many] }
+      aggregate = aggregates_by_name[target[:aggregate]]
+      word = field_key.to_s.delete_suffix("_field")
+      return entity_head_skip_reason(target[:aggregate], "#{word} target", "reduce") unless aggregate
+
+      value_objects_by_name = aggregate[:value_objects].to_h { |vo| [vo[:name], vo] }
+      field = read_model[field_key].to_s
+      kind = query_field_kind(aggregate, field, value_objects_by_name)
+      return skip(field_key.to_s, "#{word} names #{field.inspect}, but #{target[:aggregate]} declares no such attribute — not generated yet") if kind == :unknown
+
+      if BOOLEAN_AGGREGATION_FIELDS.include?(field_key)
+        return nil if query_field_boolean?(aggregate, field, value_objects_by_name)
+
+        return skip(field_key.to_s, "#{word} names #{field.inspect} on #{target[:aggregate]}, which is not boolean — #{word} needs a " \
+               "true/false field — not generated yet")
+      end
+
+      return skip(field_key.to_s, "#{word} names #{field.inspect} on #{target[:aggregate]}, which is not numeric — #{word} needs a numeric " \
+             "field (a bare number, or a value object carrying one) — not generated yet") unless kind == :number
+
+      if INTEGER_ONLY_AGGREGATION_FIELDS.include?(field_key)
+        return nil if query_field_numeric_type(aggregate, field, value_objects_by_name) == "Integer"
+
+        return skip(field_key.to_s, "#{word} names #{field.inspect} on #{target[:aggregate]}, which is a Float field — #{word} admits " \
+               "only an Integer field (summing/averaging Floats cannot be made to agree, byte for byte, between " \
+               "Ruby and Rust) — not generated yet")
+      end
+
+      nil
+    end
+
+    # Whether a field (or dotted path) reduces specifically to a `TrueClass`/`FalseClass` —
+    # `any`/`all` need this, distinct from `query_field_kind`'s coarser `:other` bucket.
+    def query_field_boolean?(aggregate, field, value_objects_by_name)
+      segments = field.to_s.split(".")
+      attr = aggregate[:attributes].find { |a| a[:name].to_s == segments.first }
+      return false unless attr && !attr[:list]
+
+      query_type_boolean?(attr[:type].to_s, segments[1..] || [], value_objects_by_name)
+    end
+
+    def query_type_boolean?(type_name, segments, value_objects_by_name)
+      if segments.empty?
+        return true if %w[TrueClass FalseClass].include?(type_name)
+        return false if reference_type?(type_name)
+
+        vo = value_objects_by_name[type_name]
+        return false unless vo
+        return query_type_boolean?(vo[:attributes].first[:type].to_s, [], value_objects_by_name) if vo[:attributes].size == 1
+
+        false
+      else
+        vo = value_objects_by_name[type_name]
+        return false unless vo
+
+        member = vo[:attributes].find { |a| a[:name].to_s == segments.first }
+        return false if member.nil? || member[:list]
+
+        query_type_boolean?(member[:type].to_s, segments[1..] || [], value_objects_by_name)
+      end
+    end
+
+    # The winning member's own type name for a numeric field ("the sole numeric member wins",
+    # mirroring `query_vo_collapse_kind`) — "Integer" or "Float" distinctly, where
+    # `query_field_kind`'s own `:number` collapses both; `nil` for anything else. `sum`/`avg`
+    # need the distinction (ADR 0078).
+    def query_field_numeric_type(aggregate, field, value_objects_by_name)
+      segments = field.to_s.split(".")
+      attr = aggregate[:attributes].find { |a| a[:name].to_s == segments.first }
+      return nil unless attr && !attr[:list]
+
+      query_type_numeric_type(attr[:type].to_s, segments[1..] || [], value_objects_by_name)
+    end
+
+    def query_type_numeric_type(type_name, segments, value_objects_by_name)
+      if segments.empty?
+        return type_name if %w[Integer Float].include?(type_name)
+        return nil if reference_type?(type_name)
+
+        vo = value_objects_by_name[type_name]
+        return nil unless vo
+
+        numeric_member = vo[:attributes].find { |a| %w[Integer Float].include?(a[:type].to_s) }
+        return numeric_member[:type].to_s if numeric_member
+        return query_type_numeric_type(vo[:attributes].first[:type].to_s, [], value_objects_by_name) if vo[:attributes].size == 1
+
+        nil
+      else
+        vo = value_objects_by_name[type_name]
+        return nil unless vo
+
+        member = vo[:attributes].find { |a| a[:name].to_s == segments.first }
+        return nil if member.nil? || member[:list]
+
+        query_type_numeric_type(member[:type].to_s, segments[1..] || [], value_objects_by_name)
+      end
+    end
+
+    # Nested entity names across every aggregate (recursively) — an
+    # `include` naming one of these is generated as an empty head, since
+    # entities have no rows of their own to project.
+    def nested_entity_names(aggregates_by_name)
+      collect = lambda do |owners|
+        owners.flat_map { |owner| Array(owner[:entities]).flat_map { |entity| [entity[:name].to_s, *collect.call([entity])] } }
+      end
+      collect.call(aggregates_by_name.values)
+    end
+
+    def entity_head_skip_reason(aggregate_name, role, purpose)
+      skip("include_entity_head", "includes #{aggregate_name}, a nested entity, as the #{role} — an entity has no rows of its own " \
+                                  "(ReadModelInterpreter#records reads it as empty), so there is nothing to #{purpose} — not generated yet")
+    end
+
+    def read_model_head_skip_reason(head, aggregates_by_name, unsupported_names)
+      target = aggregates_by_name[head[:aggregate]]
+      unless target
+        return nil if nested_entity_names(aggregates_by_name).include?(head[:aggregate].to_s)
+
+        return skip("include_undeclared_aggregate", "includes #{head[:aggregate]}, which this domain never declares")
+      end
+      return skip("include_unsupported_aggregate", "includes #{head[:aggregate]}, which this generator couldn't itself generate " \
+                                                   "(unsupported attribute type — see this domain's own aggregate-level manifest entry)") if unsupported_names.include?(head[:aggregate])
+
+      nil
+    end
+
+    # `group_by` eligibility, narrowed to the one shape the corpus declares:
+    # a single rootless head, group_by alone (build time already guarantees
+    # at most one many-side head whenever group_by is declared at all).
+    def group_by_skip_reason(read_model, aggregates_by_name, unsupported_names)
+      heads = read_model[:aggregate_heads]
+      return skip("group_by", "declares group_by across #{heads.size} aggregate heads — not generated yet (only a single, rootless head is)") if heads.size != 1
+      return skip("group_by", "declares group_by on a NON-rootless read model (reference_to #{read_model[:reference_target]}) — not generated yet") unless read_model[:reference_target].nil?
+      if read_model[:count] || AGGREGATION_FIELD_KEYS.any? { |key| read_model[key] }
+        return skip("group_by", "declares group_by alongside a reduction — not generated yet")
+      end
+      return skip("group_by", "declares group_by alongside where/order_by/limit/offset — not generated yet") if Array(read_model[:wheres]).any? || read_model[:order_by] || read_model[:limit] || read_model[:offset]
+      return skip("group_by", "declares group_by with an authorize policy — not generated yet") if read_model[:authorization]
+
+      head = heads.first
+      reason = read_model_head_skip_reason(head, aggregates_by_name, unsupported_names)
+      return reason if reason
+
+      aggregate = aggregates_by_name[head[:aggregate]]
+      return entity_head_skip_reason(head[:aggregate], "group_by head", "group") unless aggregate
+      lifecycle_field = aggregate[:lifecycle] && aggregate[:lifecycle][:field].to_s
+      Array(read_model[:group_by]).each do |row|
+        field_s = row[:field].to_s
+        next if aggregate[:attributes].any? { |a| a[:name].to_s == field_s }
+        next if field_s == lifecycle_field
+
+        return skip("group_by", "group_by names #{field_s.inspect}, but #{aggregate[:name]} declares no such attribute — not generated yet")
+      end
+
+      nil
+    end
+
+    # Compiles already-confirmed-generable hop wheres into the wire shape
+    # ReferenceHopCondition expects.
+    def read_model_hop_conditions(domain_name, hop_wheres, aggregate, aggregates_by_name)
+      hop_wheres.map do |where|
+        hop = query_hop_plan(aggregate, where[:field].to_s, aggregates_by_name)
+        raw_value = where[:value].to_s
+        symbol = raw_value.start_with?(":")
+        {
+          via_field: hop[:via_field],
+          target_aggregate: "#{domain_name}::#{hop[:target_aggregate]}",
+          through: hop[:through].map { |step| { via_field: step[:via_field], target_aggregate: "#{domain_name}::#{step[:target_aggregate]}" } },
+          inner_field: hop[:inner_field],
+          op: where[:op].to_s,
+          arg: symbol ? raw_value.delete_prefix(":") : nil,
+          literal: symbol ? nil : Hecks::Literal.read(raw_value),
+        }
+      end
+    end
+
+    def emit_reference_hop_condition(hop)
+      comparator_expr = "crate::kernel::query_comparators::QueryComparator::#{query_comparator_variant(hop[:op])}"
+      through = Array(hop[:through]).map do |step|
+        "crate::kernel::read_model::HopStep { via_field: #{step[:via_field].inspect}, target_aggregate: #{step[:target_aggregate].inspect} }"
+      end
+      "crate::kernel::read_model::ReferenceHopCondition { via_field: #{hop[:via_field].inspect}, " \
+        "target_aggregate: #{hop[:target_aggregate].inspect}, through: &[#{through.join(', ')}], " \
+        "inner_field: #{hop[:inner_field].inspect}, " \
+        "inner_comparator: #{comparator_expr}, inner_value: #{emit_query_condition_value(hop)} },"
+    end
+
+    # Baked in once at codegen time — the compiled kernel has no runtime
+    # attribute-type reflection. Includes every reference field regardless
+    # of whether its target is a head here; the matcher simply won't match.
+    def read_model_reference_fields(head_aggregate)
+      head_aggregate[:attributes].filter_map do |attr|
+        target = reference_target(attr[:type])
+        next unless target
+
+        { target: target, field: attr[:name] }
+      end
+    end
+
+    def emit_reference_field(domain_name, reference_field)
+      qualified_target = "#{domain_name}::#{reference_field[:target]}"
+      "crate::kernel::read_model::ReferenceField { target_aggregate: #{qualified_target.inspect}, " \
+        "field: #{reference_field[:field].to_s.inspect} }"
+    end
+
+    # Compiles one declared `include`. `is_root` is precomputed here rather
+    # than re-compared at runtime; the root has no reference_fields since
+    # it's fetched directly by id, never matched by reference.
+    def emit_read_model_head(domain_name, head, is_root, aggregates_by_name)
+      head_aggregate = aggregates_by_name[head[:aggregate]]
+      reference_fields = is_root || head_aggregate.nil? ? [] : read_model_reference_fields(head_aggregate)
+      reference_fields_expr = reference_fields.map { |rf| emit_reference_field(domain_name, rf) }.join(", ")
+      qualified_aggregate = "#{domain_name}::#{head[:aggregate]}"
+
+      "crate::kernel::read_model::ReadModelHead { aggregate: #{qualified_aggregate.inspect}, " \
+        "as_name: #{head[:as].to_s.inspect}, many: #{head[:many] ? 'true' : 'false'}, " \
+        "is_root: #{is_root ? 'true' : 'false'}, reference_fields: &[#{reference_fields_expr}] }"
+    end
+
+    # Compiles a declared order_by into Rust's ReadModelOrderBy; `descending`
+    # collapses the desc/asc string check once, at codegen time.
+    def emit_read_model_order_by(order_by, null_semantics = nil)
+      descending = order_by[:direction].to_s == "desc" ? "true" : "false"
+      "crate::kernel::read_model::ReadModelOrderBy { field: #{order_by[:field].to_s.inspect}, descending: #{descending}, " \
+        "nulls: #{null_semantics_variant(null_semantics)} }"
+    end
+
+    # Compiles a declared limit into a Literal or an Arg reference; a
+    # non-Arg value is already confirmed to be a real integer literal.
+    def emit_read_model_limit(limit)
+      raw = limit[:value].to_s
+      return "crate::kernel::read_model::ReadModelLimit::Arg(#{raw.delete_prefix(':').inspect})" if raw.start_with?(":")
+
+      "crate::kernel::read_model::ReadModelLimit::Literal(#{raw.to_i})"
+    end
+
+    # ReadModelOffset is a type alias of ReadModelLimit, so this reuses
+    # emit_read_model_limit and swaps only the spelled type name.
+    def emit_read_model_offset(offset) = emit_read_model_limit(offset).sub("read_model::ReadModelLimit::", "read_model::ReadModelOffset::")
+
+    # One targeted head's own where/order_by/offset/limit, compiled to plain
+    # data for `emit_filtered_head`. Hop wheres need a different wire shape
+    # (ReferenceHopCondition) than local ones, so they're split out here
+    # rather than reused wholesale; every clause has already been confirmed
+    # resolvable or generable by read_model_options_content_skip_reason.
+    def filtered_head_def(domain_name, read_model, head, many_heads, aggregates_by_name)
+      aggregate = aggregates_by_name[head[:aggregate]]
+      head_query = read_model_head_query(read_model, head, many_heads)
+      local_wheres, hop_wheres = head_query[:wheres].partition { |w| query_hop_plan(aggregate, w[:field].to_s, aggregates_by_name).nil? }
+      conditions_source = head_query.merge(wheres: local_wheres)
+
+      {
+        as_name: head[:as].to_s,
+        conditions: head_query[:authorization] ? query_conditions_with_authorization(conditions_source) : query_conditions(conditions_source),
+        reference_hop_conditions: read_model_hop_conditions(domain_name, hop_wheres, aggregate, aggregates_by_name),
+        order_by: head_query[:order_by] ? emit_read_model_order_by(head_query[:order_by], read_model[:null_semantics]) : nil,
+        offset: head_query[:offset] ? emit_read_model_offset(head_query[:offset]) : nil,
+        limit: head_query[:limit] ? emit_read_model_limit(head_query[:limit]) : nil,
+      }
+    end
+
+    # Compiles a whole declared read model to plain data for
+    # `emit_read_model_def`. `verb` uses the read model's declared name
+    # ("Domain.Name"), the same convention queries.rb picks for a named
+    # query — `kernel/cli.rs` tells the two shapes apart by the "::" that
+    # only a Domain::Aggregate.Name query verb has before the first ".".
+    #
+    # `filtered_heads` holds one entry per head `read_model_filtered_heads`
+    # names; skip_reason above already refused anything whose content wasn't
+    # generable. `authorization` (the `ReadModelDef`-level tenant-arg check)
+    # only ever applies to a single many-side head — `on:` doesn't extend to
+    # `tenant:` (ADR 0055's own scope limit).
+    def read_model_def(domain_name, read_model, aggregates_by_name)
+      heads = read_model[:aggregate_heads].map do |head|
+        is_root = head[:aggregate].to_s == read_model[:reference_target].to_s
+        emit_read_model_head(domain_name, head, is_root, aggregates_by_name)
+      end
+
+      many_heads = read_model_many_heads(read_model)
+      filtered_heads = read_model_filtered_heads(read_model).map { |head| filtered_head_def(domain_name, read_model, head, many_heads, aggregates_by_name) }
+      sole_head_as = many_heads.size == 1 ? many_heads.first[:as] : nil
+      group_by_fn_name, group_by_fn_body = read_model_group_by_fn(read_model, aggregates_by_name)
+
+      {
+        verb: "#{domain_name}.#{read_model[:name]}",
+        reference_name: read_model[:reference_name] ? read_model[:reference_name].to_s : nil,
+        heads: heads,
+        filtered_heads: filtered_heads,
+        authorization: sole_head_as ? emit_query_authorization(read_model[:name], read_model[:authorization]) : nil,
+        group_by_fn: group_by_fn_name,
+        group_by_fn_body: group_by_fn_body,
+        count: !!read_model[:count],
+        median_field: read_model[:median_field] ? read_model[:median_field].to_s : nil,
+        sum_field: read_model[:sum_field] ? read_model[:sum_field].to_s : nil,
+        avg_field: read_model[:avg_field] ? read_model[:avg_field].to_s : nil,
+        min_field: read_model[:min_field] ? read_model[:min_field].to_s : nil,
+        max_field: read_model[:max_field] ? read_model[:max_field].to_s : nil,
+        percentile_field: read_model[:percentile_field] ? read_model[:percentile_field].to_s : nil,
+        percentile_at: read_model[:percentile_field] ? read_model[:percentile_at] : nil,
+        any_field: read_model[:any_field] ? read_model[:any_field].to_s : nil,
+        all_field: read_model[:all_field] ? read_model[:all_field].to_s : nil,
+      }
+    end
+
+    # The generated group_by transform fn's name and body, or `[nil, nil]` when this read model
+    # declares no `group_by` at all. Split out of `read_model_def` to keep its own complexity down.
+    def read_model_group_by_fn(read_model, aggregates_by_name)
+      group_by_fields = Array(read_model[:group_by]).map { |row| row[:field].to_s }
+      return [nil, nil] if group_by_fields.empty?
+
+      fn_name = "group_by_#{read_model[:name].to_s.downcase}"
+      root_aggregate = aggregates_by_name[read_model[:aggregate_heads].first[:aggregate]]
+      [fn_name, emit_group_by_transform(fn_name, read_model[:name].to_s, root_aggregate, group_by_fields)]
+    end
+
+    # Generates the group_by transform fn by name, since the kernel's own
+    # generic `run` only ever holds already-serialized Json — which value
+    # object unwraps to a bare scalar is a type-level fact only codegen has.
+    #
+    # It re-attaches `id`, keeps only real declared attributes plus any
+    # `projects` field while excluding Rust-only synthetic fields (ADR 0049),
+    # and recursively unwraps single-attribute value objects. Actual grouping
+    # is `kernel::read_model::nest`, which refuses a second row per leaf
+    # unless `group_by_leaf_check` found the key path covers the identity.
+    def emit_group_by_transform(fn_name, read_model_name, aggregate, group_by_fields)
+      value_objects_by_name = aggregate[:value_objects].to_h { |vo| [vo[:name].to_s, vo] }
+      lifecycle_field = aggregate[:lifecycle] && aggregate[:lifecycle][:field].to_s
+      fields = aggregate[:attributes] + Projector.projected_field_pseudo_attributes(aggregate)
+      kept_keys = fields.map { |a| a[:name].to_s } + ["id"] + (lifecycle_field ? [lifecycle_field] : [])
+      keep_cond = kept_keys.map { |k| "k == #{k.inspect}" }.join(" || ")
+
+      arms = fields.map do |a|
+        unwrapped = unwrap_json_expr("v", a[:type].to_s, a[:list], aggregate, value_objects_by_name)
+        "#{a[:name].to_s.inspect} => #{unwrapped},"
+      end.join("\n                    ")
+
+      fields_literal = "&[#{group_by_fields.map(&:inspect).join(', ')}]"
+      leaf_check = group_by_leaf_check(read_model_name, aggregate, group_by_fields)
+
+      <<~RUST.rstrip
+        pub fn #{fn_name}(rows: Vec<(String, crate::kernel::Json)>) -> Result<crate::kernel::Json, crate::kernel::Refusal> {
+            let unwrapped: Vec<crate::kernel::Json> = rows
+                .into_iter()
+                .map(|(id, record)| {
+                    let wrapped = crate::kernel::repository::row_json(id, record);
+                    match wrapped {
+                        crate::kernel::Json::Object(fields) => crate::kernel::Json::Object(
+                            fields
+                                .into_iter()
+                                .filter(|(k, _)| #{keep_cond})
+                                .map(|(k, v)| {
+                                    let new_v = match k.as_str() {
+                    #{arms}
+                                        _ => v,
+                                    };
+                                    (k, new_v)
+                                })
+                                .collect(),
+                        ),
+                        other => other,
+                    }
+                })
+                .collect();
+            crate::kernel::read_model::nest(unwrapped, #{fields_literal}, #{leaf_check})
+        }
+      RUST
+    end
+
+    # A key path naming every identity field of the grouped aggregate can't
+    # collide, so its leaves go unchecked; any other refuses a second row
+    # per leaf (ADR 0061). `identified_by` in the IR holds identity paths.
+    def group_by_leaf_check(read_model_name, aggregate, group_by_fields)
+      identity = Array(aggregate[:identified_by]).map { |path| path.to_s.split(".").first }.uniq
+      return "crate::kernel::read_model::LeafCheck::IdentityCovered" if identity.any? && (identity - group_by_fields).empty?
+
+      "crate::kernel::read_model::LeafCheck::RefuseCollision(#{read_model_name.inspect})"
+    end
+
+    # Ports Value.materialize_unwrapped: a single-attribute value object
+    # unwraps to its bare field; a multi-attribute one or an entity keeps
+    # its object shape but recurses into each field; scalars and lists
+    # (mapped element-wise) pass through the same logic unchanged.
+    def unwrap_json_expr(expr, type_name, list, aggregate, value_objects_by_name)
+      if list
+        inner = unwrap_json_expr("item", type_name, false, aggregate, value_objects_by_name)
+        return "match #{expr} { crate::kernel::Json::Array(items) => crate::kernel::Json::Array(items.into_iter().map(|item| #{inner}).collect()), other => other }"
+      end
+
+      vo = value_objects_by_name[type_name]
+      entity = (aggregate[:entities] || []).find { |e| e[:name].to_s == type_name.to_s }
+      fields_meta = vo ? vo[:attributes] : (entity ? entity[:attributes] : nil)
+      return expr unless fields_meta
+
+      if vo && fields_meta.size == 1
+        field = fields_meta.first
+        unwrapped = unwrap_json_expr("field_value", field[:type].to_s, field[:list], aggregate, value_objects_by_name)
+        return "match #{expr} { crate::kernel::Json::Object(fields) => fields.into_iter().find(|(k, _)| k == #{field[:name].to_s.inspect}).map(|(_, field_value)| #{unwrapped}).unwrap_or(crate::kernel::Json::Null), other => other }"
+      end
+
+      inner_arms = fields_meta.map do |f|
+        unwrapped = unwrap_json_expr("v", f[:type].to_s, f[:list], aggregate, value_objects_by_name)
+        "#{f[:name].to_s.inspect} => #{unwrapped},"
+      end.join(" ")
+      "match #{expr} { crate::kernel::Json::Object(fields) => crate::kernel::Json::Object(fields.into_iter().map(|(k, v)| { let new_v = match k.as_str() { #{inner_arms} _ => v }; (k, new_v) }).collect()), other => other }"
+    end
+
+    # One `FilteredHead` entry, always emitted as a single line — matching
+    # the codebase's own established idiom for every OTHER leaf struct
+    # (ReadModelHead, ReferenceField, ReferenceHopCondition, QueryCondition
+    # are all single-line too; only the top-level ReadModelDef/QueryDef get
+    # pretty multi-line formatting with their arrays broken across lines).
+    def emit_filtered_head(filtered_head_def)
+      conditions = filtered_head_def[:conditions].map { |c| emit_query_condition(c) }.join(" ")
+      reference_hop_conditions = filtered_head_def[:reference_hop_conditions].map { |h| emit_reference_hop_condition(h) }.join(" ")
+      order_by = filtered_head_def[:order_by] ? "Some(#{filtered_head_def[:order_by]})" : "None"
+      offset = filtered_head_def[:offset] ? "Some(#{filtered_head_def[:offset]})" : "None"
+      limit = filtered_head_def[:limit] ? "Some(#{filtered_head_def[:limit]})" : "None"
+
+      "crate::kernel::read_model::FilteredHead { as_name: #{filtered_head_def[:as_name].inspect}, " \
+        "conditions: &[#{conditions}], reference_hop_conditions: &[#{reference_hop_conditions}], " \
+        "order_by: #{order_by}, offset: #{offset}, limit: #{limit} },"
+    end
+
+    def emit_read_model_def(read_model_def)
+      heads = read_model_def[:heads].map { |head| "        #{head}," }.join("\n")
+      filtered_heads = read_model_def[:filtered_heads].map { |fh| "        #{emit_filtered_head(fh)}" }.join("\n")
+      authorization = read_model_def[:authorization] ? "Some(#{read_model_def[:authorization]})" : "None"
+      reference_name = read_model_def[:reference_name] ? "Some(#{read_model_def[:reference_name].inspect})" : "None"
+      group_by = read_model_def[:group_by_fn] ? "Some(#{read_model_def[:group_by_fn]})" : "None"
+      count = read_model_def[:count] ? "true" : "false"
+      median_field = read_model_def[:median_field] ? "Some(#{read_model_def[:median_field].inspect})" : "None"
+      sum_field = read_model_def[:sum_field] ? "Some(#{read_model_def[:sum_field].inspect})" : "None"
+      avg_field = read_model_def[:avg_field] ? "Some(#{read_model_def[:avg_field].inspect})" : "None"
+      min_field = read_model_def[:min_field] ? "Some(#{read_model_def[:min_field].inspect})" : "None"
+      max_field = read_model_def[:max_field] ? "Some(#{read_model_def[:max_field].inspect})" : "None"
+      percentile_field = read_model_def[:percentile_field] ? "Some(#{read_model_def[:percentile_field].inspect})" : "None"
+      percentile_at = read_model_def[:percentile_at] ? "Some(#{Float(read_model_def[:percentile_at])}_f64)" : "None"
+      any_field = read_model_def[:any_field] ? "Some(#{read_model_def[:any_field].inspect})" : "None"
+      all_field = read_model_def[:all_field] ? "Some(#{read_model_def[:all_field].inspect})" : "None"
+
+      <<~RUST.rstrip
+        crate::kernel::read_model::ReadModelDef {
+            verb: #{read_model_def[:verb].inspect},
+            reference_name: #{reference_name},
+            heads: &[
+        #{heads}
+            ],
+            filtered_heads: &[
+        #{filtered_heads}
+            ],
+            authorization: #{authorization},
+            group_by: #{group_by},
+            count: #{count},
+            median_field: #{median_field},
+            sum_field: #{sum_field},
+            avg_field: #{avg_field},
+            min_field: #{min_field},
+            max_field: #{max_field},
+            percentile_field: #{percentile_field},
+            percentile_at: #{percentile_at},
+            any_field: #{any_field},
+            all_field: #{all_field},
+        },
+      RUST
+    end
+
+    # Must dedent-match `rust/src/exemplar/read_models.rs`'s own
+    # TMPL:read_model_table placeholder row exactly — Exemplar.render
+    # substitutes by literal substring.
+    READ_MODEL_TABLE_ROW_PLACEHOLDER = <<~RUST.rstrip
+      crate::kernel::read_model::ReadModelDef {
+          verb: "tmpl_verb",
+          reference_name: Some("tmpl_reference_name"),
+          heads: &[
+              crate::kernel::read_model::ReadModelHead {
+                  aggregate: "tmpl_aggregate",
+                  as_name: "tmpl_as_name",
+                  many: true,
+                  is_root: false,
+                  reference_fields: &[
+                      crate::kernel::read_model::ReferenceField { target_aggregate: "tmpl_target_aggregate", field: "tmpl_field" },
+                  ],
+              },
+          ],
+          filtered_heads: &[
+              crate::kernel::read_model::FilteredHead { as_name: "tmpl_as_name", conditions: &[crate::kernel::QueryCondition { field: "tmpl_field", comparator: crate::kernel::query_comparators::QueryComparator::Eq, value: crate::kernel::QueryConditionValue::Literal("tmpl_literal") },], reference_hop_conditions: &[crate::kernel::read_model::ReferenceHopCondition { via_field: "tmpl_via_field", target_aggregate: "tmpl_target_aggregate", through: &[crate::kernel::read_model::HopStep { via_field: "tmpl_via_field", target_aggregate: "tmpl_target_aggregate" }], inner_field: "tmpl_inner_field", inner_comparator: crate::kernel::query_comparators::QueryComparator::Eq, inner_value: crate::kernel::QueryConditionValue::Literal("tmpl_literal") },], order_by: Some(crate::kernel::read_model::ReadModelOrderBy { field: "tmpl_order_field", descending: true, nulls: crate::kernel::query_ordering::NullsMode::Last }), offset: Some(crate::kernel::read_model::ReadModelOffset::Literal(1)), limit: Some(crate::kernel::read_model::ReadModelLimit::Literal(5)) },
+          ],
+          authorization: Some(crate::kernel::named_query::TenantAuth { query_name: "tmpl_query_name", tenant_field: "tmpl_tenant_field", policy: "tmpl_policy" }),
+          group_by: None,
+          count: false,
+          median_field: None,
+          sum_field: None,
+          avg_field: None,
+          min_field: None,
+          max_field: None,
+          percentile_field: None,
+          percentile_at: None,
+          any_field: None,
+          all_field: None,
+      },
+    RUST
+
+    # The read model table `kernel::read_model::run` walks at runtime — one
+    # row per read model that `read_model_skip_reason` lets through; a
+    # skipped read model simply has no row here.
+    def emit_read_model_table(read_model_defs)
+      rows = read_model_defs.map { |rmd| emit_read_model_def(rmd) }
+      Exemplar.render("read_model_table", READ_MODEL_TABLE_ROW_PLACEHOLDER => rows.join("\n"))
+    end
+  end
+end