Let a lookahead resolver record an error for a descendant field, closes #1340

- QueryContext#record_lookahead_error lets any lookahead-driven resolver flag
  itself or a descendant lookahead node as invalid without failing the
  recording field's whole subtree (which is what raising there would do).
- LookaheadErrors keys each record by the flagged node's absolute, index-free
  response path, found by walking down from context.query.lookahead; a field
  matches when its current_path, minus list indices, equals that path. See
  docs/adr/0001-lookahead-error-record-key.md for why that key.
- Misuse raises Errors::ConfigError at the call site: a node that isn't
  selected at or beneath the field being resolved (a node from an unrelated
  part of the query, or a typo'd Lookahead#selection name, which yields a null
  object) can't be recorded. Nothing to detect after the fact.
- GraphQLAdapterBuilder's resolver lambdas check for a matching record before
  resolving and return a GraphQL::ExecutionError (halting just that
  field/subtree) instead of running the registered resolver.
- Replaces the two-spot approximatePercentile workaround:
  Aggregation::QueryAdapter#computation_for now records the error instead of
  silently omitting the computation, and AggregatedValues#resolve no longer
  needs its own validation/error-path logic.

Because the key ignores list indices, one record can match many response
positions -- every bucket of an aggregation, say -- each producing its own
error at its own path, which is what lets a client tell an errored null from a
real one. That's also why datastore query memoization needs no involvement: a
cache hit implies identical lookahead.ast_nodes (which hash by identity), so
the response path recorded on the miss still applies.

Generated with Claude Code

Author: myronmarston

docs/adr/0001-lookahead-error-record-key.md

@@ -0,0 +1,55 @@
+# Identify lookahead errors by response path, not by field or AST node
+
+A resolver that builds its datastore query from a lookahead can discover that a *descendant* field is
+invalid (e.g. `approximatePercentile(percentile: 150)`). It cannot raise `GraphQL::ExecutionError` for
+that descendant — the raise would fail the recording field's entire subtree instead of the one bad
+leaf. So the recording field records a **lookahead error** and ElasticGraph fails the flagged field
+when it is resolved. This ADR records how a recorded error is matched to the field it is about.
+
+Terms used here:
+
+- **Recording field** — the field whose resolver holds the lookahead and observes the problem.
+- **Flagged node** — the lookahead node, at any depth beneath the recording field, that the recording
+  field identified as erroneous.
+- **Lookahead error** — an error about a flagged node, discovered by a recording field rather than by
+  the flagged node's own resolver.
+
+**Decision**: a record is keyed by the flagged node's **absolute, index-free response path**, found by
+walking down from the query's root lookahead (`context.query.lookahead`) to the flagged node's AST
+nodes. At resolve time a field matches if its `context.current_path`, with list indices dropped, equals
+that path.
+
+## Considered Options
+
+| Option | Why rejected |
+|---|---|
+| `[schema field, args]` | A schema field is static, so it cannot distinguish an invalid selection from a valid one of the same field elsewhere in the query. |
+| AST node identity | Would require the `:ast_node` extra on every field ElasticGraph resolves — a cost paid by every query for a rare feature. |
+| Recording field's exact path (indices included) + relative path | Expresses a per-list-element distinction that cannot arise (see below), at the cost of the recording field having to bind its records to a path, which datastore query memoization then has to participate in. |
+
+## Consequences
+
+- **The caller passes only the flagged node**, and the path is derived from `context.current_path`, so
+  there is no way to misidentify the recording field. A node that isn't selected at or beneath
+  `current_path` — a typo'd `Lookahead#selection` name, or a node from an unrelated part of the query —
+  raises `Errors::ConfigError` at the point of misuse. That leaves nothing to detect after the fact.
+- **A record may match several response positions.** A list *between* the query root and the flagged
+  node collapses its indices, so one record can match every bucket of an aggregation. Each match
+  produces its own error with its own path, which is what the [GraphQL
+  spec](https://spec.graphql.org/October2021/#sec-Errors) requires: an execution error occurs at a
+  specific response position, and its `path` is what lets clients tell an errored `null` from a real
+  one. Nothing is lost, because a lookahead error is a property of the query, not of the data — a
+  recording field cannot legitimately mean "bucket 1 only." `Resolvers::QueryAdapter` enforces as much
+  for datastore query adapters, which must be pure functions of `(field, args, lookahead)`.
+- **A record may match nothing**, legitimately, when execution never reaches the flagged position
+  (e.g. the recording field resolved to an empty list). Nothing to report: unlike a raised error, an
+  unreached lookahead error is simply inert.
+- **A node can flag itself, not just a descendant**, since its own path matches. This lets any
+  `:lookahead`-accepting resolver report its own invalid args through the same mechanism it would use
+  for a descendant (by returning `QueryContext#matching_lookahead_error`) rather than raising — handy
+  when the resolver wants one consistent way to fail a field.
+- **Datastore query memoization needs no involvement.** Queries are memoized on
+  `(field, args, lookahead)`, so on a cache hit the build — and its recording — is skipped. That's
+  correct precisely because the key is index-free: a cache hit implies identical `lookahead.ast_nodes`
+  (which hash by identity), hence the same document position, hence the same index-free path as the
+  record made on the miss.

elasticgraph-graphql/lib/elastic_graph/graphql/aggregation/function_adapter.rb

@@ -16,9 +16,10 @@ module Aggregation
       # the datastore omitted.
       #
       # When an adapter's `extract_args` is given args it considers invalid, it yields an error
-      # message instead of returning extracted args. Each caller passes a block that exits
-      # non-locally (the args of an invalid field are never used), which lets a field with invalid
-      # args be handled without disrupting the sibling fields being processed alongside it.
+      # message instead of returning extracted args. The caller (`QueryAdapter#computation_for`)
+      # passes a block that exits non-locally (the args of an invalid field are never used), which
+      # lets a field with invalid args be handled without disrupting the sibling fields being
+      # processed alongside it.
       #
       # @private
       module FunctionAdapter

elasticgraph-graphql/lib/elastic_graph/graphql/aggregation/query_adapter.rb

@@ -63,6 +63,7 @@ def call(query:, lookahead:, args:, field:, context:)
           aggregation_query = build_aggregation_query_for(
             aggregations_node,
             field: field,
+            context: context,
             grouping_adapter: CompositeGroupingAdapter,
             # Filters on root aggregations applied to the search query body itself instead of
             # using a filter aggregation, like sub-aggregations do, so we don't want a filter
@@ -95,7 +96,7 @@ def extract_aggregation_node(lookahead, field, graphql_query)
           )
         end
 
-        def build_aggregation_query_for(aggregations_node, field:, grouping_adapter:, nested_path: [], unfiltered: false)
+        def build_aggregation_query_for(aggregations_node, field:, context:, grouping_adapter:, nested_path: [], unfiltered: false)
           aggregation_name = name_of(_ = aggregations_node.ast_nodes.first)
 
           # Get the AST node for the `nodes` subfield (e.g. from `fooAggregations { nodes { ... } }`)
@@ -130,8 +131,8 @@ def build_aggregation_query_for(aggregations_node, field:, grouping_adapter:, ne
           Query.new(
             name: aggregation_name,
             groupings: build_groupings_from(node_node, aggregation_name, from_field_path: nested_path),
-            computations: build_computations_from(node_node, from_field_path: nested_path),
-            sub_aggregations: build_sub_aggregations_from(node_node, parent_nested_path: nested_path),
+            computations: build_computations_from(node_node, context: context, from_field_path: nested_path),
+            sub_aggregations: build_sub_aggregations_from(node_node, context: context, parent_nested_path: nested_path),
             needs_doc_count: count_detail_node.selected? || node_node.selects?(element_names.count),
             needs_doc_count_error: needs_doc_count_error,
             paginator: build_paginator_for(aggregations_node),
@@ -179,22 +180,22 @@ def transform_node_to_clauses(node, parent_path: [], &clause_builder)
           end
         end
 
-        def build_computations_from(node_node, from_field_path: [])
+        def build_computations_from(node_node, context:, from_field_path: [])
           aggregated_values_node = node_node.selection(element_names.aggregated_values)
 
           build_clauses_from(aggregated_values_node) do |node, field, field_path|
             if field.aggregated?
               field_path = from_field_path + field_path
-              get_children_nodes(node).filter_map { |fn_node| computation_for(fn_node, field_path) }
+              get_children_nodes(node).filter_map { |fn_node| computation_for(fn_node, field_path, context: context) }
             end
           end
         end
 
         # Builds the `Computation` for an aggregated value function node, or returns `nil` if the node
-        # has invalid args (e.g. an out-of-range `percentile`). We omit the computation rather than
-        # failing the whole aggregations field here: the resolver detects the same invalid args when it
-        # resolves this specific field, and can attribute the error to that field's precise path.
-        def computation_for(fn_node, field_path)
+        # has invalid args (e.g. an out-of-range `percentile`). We record a lookahead error (rather
+        # than failing the whole aggregations field here) and omit the computation; ElasticGraph fails
+        # just this one leaf, at its precise path, when GraphQL execution reaches it.
+        def computation_for(fn_node, field_path, context:)
           computed_field = field_from_node(fn_node)
           function_adapter = computed_field.function_adapter # : FunctionAdapter::adapter
           args = computed_field.args_to_schema_form(fn_node.arguments)
@@ -203,7 +204,10 @@ def computation_for(fn_node, field_path)
             source_field_path: field_path,
             leaf: PathSegment.for(field: computed_field, lookahead: fn_node),
             function_adapter: function_adapter,
-            function_args: function_adapter.extract_args(args, element_names) { return nil }
+            function_args: function_adapter.extract_args(args, element_names) do |message|
+              context.record_lookahead_error(fn_node, message)
+              return nil
+            end
           )
         end
 
@@ -306,7 +310,7 @@ def name_of(ast_node)
           ast_node.alias || ast_node.name
         end
 
-        def build_sub_aggregations_from(node_node, parent_nested_path: [])
+        def build_sub_aggregations_from(node_node, context:, parent_nested_path: [])
           key_sub_agg_pairs =
             build_clauses_from(node_node.selection(element_names.sub_aggregations)) do |node, field, field_path|
               if field.type.elasticgraph_category == :nested_sub_aggregation_connection
@@ -316,6 +320,7 @@ def build_sub_aggregations_from(node_node, parent_nested_path: [])
                   query: build_aggregation_query_for(
                     node,
                     field: field,
+                    context: context,
                     grouping_adapter: sub_aggregation_grouping_adapter,
                     nested_path: nested_path
                   )

elasticgraph-graphql/lib/elastic_graph/graphql/aggregation/resolvers/aggregated_values.rb

@@ -9,7 +9,6 @@
 require "elastic_graph/graphql/aggregation/key"
 require "elastic_graph/graphql/aggregation/path_segment"
 require "elastic_graph/support/hash_util"
-require "graphql"
 
 module ElasticGraph
   class GraphQL
@@ -21,29 +20,6 @@ def resolve(field:, object:, args:, context:, lookahead:)
 
             function_adapter = field.function_adapter # : FunctionAdapter::adapter
 
-            # `QueryAdapter` detected any invalid args when the query was built, but it can't report an
-            # error there without failing resolution of the entire aggregations field rather than just
-            # this one leaf--so it omits the datastore clause for an invalid field instead. Here, at
-            # resolve time, we're resolving this specific field, so we can report the error at the
-            # correct, precise path.
-            #
-            # `args` is already in schema form here (`GraphQLAdapterBuilder` converts it before calling
-            # `resolve`), unlike at query-build time where `QueryAdapter` converts the raw AST arguments
-            # itself--so, unlike there, we pass `args` through as-is rather than re-converting it.
-            function_adapter.extract_args(args, schema.element_names) do |message|
-              error = ::GraphQL::ExecutionError.new(message)
-
-              # Neither `context.add_error` nor `context.execution_errors.add` sets `path` for us--that
-              # only happens automatically when an `ExecutionError` is raised and returned as a field's
-              # own resolution result, which isn't the case here since we're continuing on to resolve
-              # sibling fields normally. So we set `path` ourselves from `context.current_path`, which
-              # is already the precise path to this field (e.g. `[..., "aggregatedValues", "amountCents",
-              # "p150"]`), so the error in the response is attributed to this specific field.
-              error.path = context.current_path
-              context.add_error(error)
-              return nil
-            end
-
             key = Key::AggregatedValue.new(
               aggregation_name: aggregation_name,
               field_path: field_path.map(&:name_in_graphql_query),

elasticgraph-graphql/lib/elastic_graph/graphql/lookahead_errors.rb

@@ -0,0 +1,89 @@
+# Copyright 2024 - 2026 Block, Inc.
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+#
+# frozen_string_literal: true
+
+require "elastic_graph/errors"
+require "graphql"
+
+module ElasticGraph
+  class GraphQL
+    # Tracks "lookahead errors": errors that an ancestor resolver discovers about a *descendant*
+    # field while walking its lookahead to build a datastore query, but cannot raise for (raising
+    # there would fail the ancestor's entire subtree instead of just the one bad descendant).
+    #
+    # See `docs/adr/0001-lookahead-error-record-key.md` for the design rationale behind the
+    # record key used here.
+    class LookaheadErrors
+      # A recorded error about the field selected at `path`--an absolute response path from the root
+      # of the query, with no list indices.
+      Record = ::Data.define(:path, :message, :extensions) do
+        # @implements Record
+
+        # Indices are skipped rather than compared because the flagged node's list positions don't
+        # exist yet when it is recorded, so one record can match many response positions (e.g. every
+        # bucket of an aggregation).
+        def matches?(current_path)
+          current_path.grep_v(::Integer) == path
+        end
+      end
+
+      def initialize
+        @records = [] # : Array[Record]
+      end
+
+      # Records that `node` (a lookahead node at or beneath the field being resolved at
+      # `recording_path`) is invalid, with the given `message`, making it matchable via
+      # `#matching_error_for`. `root_lookahead` is the lookahead of the query as a whole, which we
+      # walk to resolve `node` to its absolute path.
+      def record(node, message, root_lookahead:, recording_path:, extensions: nil)
+        # A node reached through a fragment spread that's used in multiple places has multiple paths;
+        # only the one(s) under the field being resolved are ours to flag.
+        prefix = recording_path.grep_v(::Integer)
+        target_ast_nodes = node.selected? ? node.ast_nodes.to_set : ::Set.new # : ::Set[::GraphQL::Language::Nodes::Field]
+        paths = find_paths(root_lookahead, target_ast_nodes, []).select { |path| path.first(prefix.size) == prefix }
+
+        if paths.empty?
+          raise Errors::ConfigError, "`record_lookahead_error` was given a lookahead node that is not " \
+            "selected at or beneath #{prefix.inspect}, the field being resolved. Note that " \
+            "`Lookahead#selection` returns a null object for an unselected (or misspelled) field."
+        end
+
+        @records.concat(paths.map { |path| Record.new(path: path, message: message, extensions: extensions) })
+      end
+
+      # Returns a `GraphQL::ExecutionError` for the first recorded error matching `current_path` (the
+      # path of the field about to be resolved), or `nil` if none match. Cheap (an `Array#find` over
+      # `@records`, empty for the overwhelmingly common query that never records a lookahead error)
+      # with no separate guard needed at call sites. A record legitimately matches nothing at all when
+      # execution never reaches the flagged position (e.g. its parent resolved to an empty list).
+      def matching_error_for(current_path)
+        record = @records.find { |r| r.matches?(current_path) }
+        return nil unless record
+
+        ::GraphQL::ExecutionError.new(record.message, extensions: record.extensions)
+      end
+
+      private
+
+      # Finds the index-free response-key path(s) from `current` down to a node whose `ast_nodes`
+      # intersect `target_ast_nodes`, including `current` itself (so a node can flag its own
+      # recording field, yielding that field's own path).
+      def find_paths(current, target_ast_nodes, path_so_far)
+        return [path_so_far] if current.ast_nodes.to_set.intersect?(target_ast_nodes)
+
+        current.selections.flat_map do |child|
+          # `Lookahead#name` returns the field's method name, not its response key, so aliased
+          # selections would collide under it. `#selections` already groups by response key
+          # (`alias || name`), so pull the response key straight off the underlying AST node.
+          first_ast_node = child.ast_nodes.first
+          response_key = first_ast_node.alias || first_ast_node.name
+          find_paths(child, target_ast_nodes, path_so_far + [response_key])
+        end
+      end
+    end
+  end
+end

elasticgraph-graphql/lib/elastic_graph/graphql/query_context.rb

@@ -8,6 +8,7 @@
 
 require "elastic_graph/errors"
 require "elastic_graph/graphql/client"
+require "elastic_graph/graphql/lookahead_errors"
 require "elastic_graph/graphql/query_details_tracker"
 require "graphql"
 
@@ -92,6 +93,42 @@ def fetch(key, *args, &block)
         super
       end
 
+      # Records that `node`, a `GraphQL::Execution::Lookahead` node at or beneath the field currently
+      # being resolved, is invalid, with the given `message`. Intended for a custom lookahead-driven
+      # resolver that discovers a problem with itself or a *descendant* field while building its
+      # datastore query, and cannot raise a `GraphQL::ExecutionError` for it there (doing so would
+      # fail this resolver's entire subtree instead of just the one bad field).
+      #
+      # `extensions`, if provided, is included verbatim under the `"extensions"` key of the error
+      # in the GraphQL response; when omitted, no `"extensions"` key is added.
+      #
+      # `node` is resolved into a matching field the next time GraphQL execution reaches it: instead
+      # of running the registered resolver, ElasticGraph fails that field with a
+      # `GraphQL::ExecutionError` built from `message`/`extensions`, without disrupting sibling
+      # fields. A resolver that flags *itself* can report the error by returning
+      # `#matching_lookahead_error`, giving it one consistent way to fail a field regardless of
+      # whether the problem is with itself or a descendant.
+      #
+      # Must be called while the recording field is being resolved, since `node` is resolved to a
+      # response path relative to `#current_path`. Raises `Errors::ConfigError` if `node` is not
+      # selected at or beneath that path.
+      def record_lookahead_error(node, message, extensions: nil)
+        current_path = self.current_path # : Array[String | Integer]
+        lookahead_errors.record(node, message, root_lookahead: query.lookahead, recording_path: current_path, extensions: extensions)
+      end
+
+      # Returns a `GraphQL::ExecutionError` for the field about to be resolved (at `#current_path`)
+      # if an ancestor resolver recorded a lookahead error matching it, or `nil` otherwise.
+      def matching_lookahead_error
+        current_path = self.current_path # : Array[String | Integer]
+        lookahead_errors.matching_error_for(current_path)
+      end
+
+      # Lazily builds (and memoizes) the `LookaheadErrors` collector for this query.
+      def lookahead_errors
+        @lookahead_errors ||= LookaheadErrors.new
+      end
+
       private
 
       def raise_if_removed_key(key)