Implement ParentManagedValue for resolver takeover (AIRBNB)

Github-Change-Id: 967108
GitOrigin-RevId: ca1230f4bddc03f25356b930ffd9dcd8d21bb006

Author: skevy

engine/api/src/main/kotlin/viaduct/engine/api/EngineExecutionContext.kt

@@ -85,6 +85,15 @@ interface EngineExecutionContext {
          * - Child plan execution: The resolved child plan variables
          */
         val variables: Map<String, Any?>
+
+        /**
+         * The policy governing how fields within this scope should be resolved.
+         *
+         * This is determined by the result of the parent field's execution.
+         * - [ResolutionPolicy.STANDARD]: Normal execution (lookup resolvers).
+         * - [ResolutionPolicy.PARENT_MANAGED]: Driven by [ParentManagedValue], skipping resolvers.
+         */
+        val resolutionPolicy: ResolutionPolicy
     }
 
     /**

engine/api/src/main/kotlin/viaduct/engine/api/ParentManagedValue.kt

@@ -0,0 +1,31 @@
+package viaduct.engine.api
+
+/**
+ * A wrapper that can be returned by a resolver to signal that it should
+ * take over the resolution of its nested selections.
+ *
+ * Returning this wrapper enables "Parent-Managed Resolution", where the parent
+ * resolver provides the full data structure for its children, bypassing individual
+ * field resolvers.
+ *
+ * ## Use Cases
+ * - **Adapters**: When wrapping legacy objects or map structures where you want to
+ *   expose the raw data directly without writing trivial resolvers for every field.
+ * - **Optimization**: When the parent can fetch the entire subtree more efficiently
+ *   than resolving each field individually.
+ *
+ * ## Behavior
+ * When the engine encounters this wrapper:
+ * 1. It unwraps the [value] and uses it as the source for the current level.
+ * 2. It switches the [ResolutionPolicy] to [ResolutionPolicy.PARENT_MANAGED] for all
+ *    nested selections.
+ * 3. Registered resolvers for child fields are **skipped**.
+ * 4. Fields are resolved using the default property data fetcher (reading properties/keys
+ *    from the [value]).
+ */
+@JvmInline
+value class ParentManagedValue(val value: Any?) {
+    init {
+        require(value !is ParentManagedValue)
+    }
+}

engine/api/src/main/kotlin/viaduct/engine/api/ResolutionPolicy.kt

@@ -0,0 +1,26 @@
+package viaduct.engine.api
+
+/**
+ * Defines the policy for resolving nested fields of an object.
+ *
+ * This policy controls whether the engine looks up and executes registered resolvers
+ * for fields, or whether it relies on simple property access on the parent object.
+ */
+enum class ResolutionPolicy {
+    /**
+     * Standard resolution: The engine looks for and executes registered field resolvers.
+     * If no resolver is found, it falls back to the default property data fetcher.
+     */
+    STANDARD,
+
+    /**
+     * Parent-managed resolution: The parent object has explicitly taken responsibility
+     * for its child fields (typically by returning a [ParentManagedValue]).
+     *
+     * In this mode:
+     * - Registered resolvers are **ignored**.
+     * - Fields are resolved purely via the default data fetcher wired for fields, typically
+     *   a `PropertyDataFetcher`.
+     */
+    PARENT_MANAGED
+}

engine/runtime/src/main/kotlin/viaduct/engine/runtime/EngineExecutionContextImpl.kt

@@ -12,6 +12,7 @@ import viaduct.engine.api.FragmentLoader
 import viaduct.engine.api.NodeResolverExecutor
 import viaduct.engine.api.RawSelectionSet
 import viaduct.engine.api.RawSelectionsLoader
+import viaduct.engine.api.ResolutionPolicy
 import viaduct.engine.api.ViaductSchema
 import viaduct.engine.runtime.select.RawSelectionSetFactoryImpl
 import viaduct.service.api.spi.FlagManager
@@ -87,6 +88,7 @@ class EngineExecutionContextImpl(
     data class FieldExecutionScopeImpl(
         override val fragments: Map<String, FragmentDefinition> = emptyMap(),
         override val variables: Map<String, Any?> = emptyMap(),
+        override val resolutionPolicy: ResolutionPolicy = ResolutionPolicy.STANDARD,
     ) : EngineExecutionContext.FieldExecutionScope
 
     override fun createNodeReference(

engine/runtime/src/main/kotlin/viaduct/engine/runtime/FieldResolutionResult.kt

@@ -2,6 +2,7 @@ package viaduct.engine.runtime
 
 import graphql.GraphQLError
 import graphql.execution.FetchedValue
+import viaduct.engine.api.ResolutionPolicy
 import viaduct.engine.runtime.context.CompositeLocalContext
 
 /**
@@ -16,6 +17,7 @@ data class FieldResolutionResult(
     val localContext: CompositeLocalContext,
     val extensions: Map<Any, Any?>,
     val originalSource: Any?,
+    val resolutionPolicy: ResolutionPolicy = ResolutionPolicy.STANDARD,
 ) {
     companion object {
         private val Any?.asCompositeLocalContext: CompositeLocalContext
@@ -26,9 +28,20 @@ data class FieldResolutionResult(
                     throw IllegalStateException("Expected CompositeLocalContext but found ${ctx::class}")
             }
 
+        fun fromErrors(errors: List<GraphQLError>,) =
+            FieldResolutionResult(
+                engineResult = null,
+                errors = errors,
+                localContext = CompositeLocalContext.empty,
+                extensions = emptyMap(),
+                originalSource = null,
+            )
+
         fun fromFetchedValue(
             engineResult: Any?,
-            fetchedValue: FetchedValue
+            fetchedValue: FetchedValue,
+            resolutionPolicy: ResolutionPolicy,
+            originalSource: Any? = fetchedValue.fetchedValue,
         ) = FieldResolutionResult(
             engineResult,
             fetchedValue.errors,
@@ -37,7 +50,8 @@ data class FieldResolutionResult(
                 is FetchedValueWithExtensions -> fetchedValue.extensions
                 else -> emptyMap()
             },
-            fetchedValue.fetchedValue,
+            originalSource,
+            resolutionPolicy,
         )
     }
 }

engine/runtime/src/main/kotlin/viaduct/engine/runtime/execution/ExecutionParameters.kt

@@ -26,6 +26,7 @@ import viaduct.engine.api.FieldCheckerDispatcherRegistry
 import viaduct.engine.api.FieldResolverDispatcherRegistry
 import viaduct.engine.api.RawSelectionSet
 import viaduct.engine.api.RequiredSelectionSetRegistry
+import viaduct.engine.api.ResolutionPolicy
 import viaduct.engine.api.TypeCheckerDispatcherRegistry
 import viaduct.engine.api.gj
 import viaduct.engine.api.instrumentation.ViaductModernGJInstrumentation
@@ -58,6 +59,7 @@ import viaduct.utils.slf4j.logger
  * @property parent Parent parameters in the traversal chain, if any
  * @property field Field currently being executed, if any
  * @property bypassChecksDuringCompletion If execution is in the context of an access check
+ * @property resolutionPolicy The resolution policy to use for this execution step
  */
 data class ExecutionParameters(
     val constants: Constants,
@@ -71,7 +73,8 @@ data class ExecutionParameters(
     val errorAccumulator: ErrorAccumulator,
     val parent: ExecutionParameters? = null,
     val field: QueryPlan.CollectedField? = null,
-    val bypassChecksDuringCompletion: Boolean = false
+    val bypassChecksDuringCompletion: Boolean = false,
+    val resolutionPolicy: ResolutionPolicy = ResolutionPolicy.STANDARD,
 ) {
     // Computed properties
     /** The ResultPath for the current level of execution */
@@ -145,6 +148,7 @@ data class ExecutionParameters(
             field = field,
             executionStepInfo = executionStepInfo,
             parent = this,
+            resolutionPolicy = resolutionPolicy,
         )
     }
 
@@ -343,6 +347,7 @@ data class ExecutionParameters(
             parentEngineResult = newParentOER,
             localContext = localContext,
             source = source,
+            resolutionPolicy = resolutionPolicy,
         )
     }
 
@@ -360,6 +365,7 @@ data class ExecutionParameters(
         engineResult: ObjectEngineResultImpl,
         localContext: CompositeLocalContext,
         source: Any?,
+        resolutionPolicy: ResolutionPolicy = this.resolutionPolicy,
     ): ExecutionParameters {
         return copy(
             parentEngineResult = engineResult, // Update parent to be the current object we're traversing into
@@ -370,6 +376,7 @@ data class ExecutionParameters(
             localContext = localContext,
             source = source,
             selectionSet = checkNotNull(field.selectionSet) { "Expected selection set to be non-null." },
+            resolutionPolicy = resolutionPolicy,
         )
     }
 

engine/runtime/src/main/kotlin/viaduct/engine/runtime/execution/FieldCompleter.kt

@@ -26,7 +26,6 @@ import viaduct.engine.runtime.ObjectEngineResultImpl
 import viaduct.engine.runtime.ObjectEngineResultImpl.Companion.ACCESS_CHECK_SLOT
 import viaduct.engine.runtime.ObjectEngineResultImpl.Companion.RAW_VALUE_SLOT
 import viaduct.engine.runtime.Value
-import viaduct.engine.runtime.context.CompositeLocalContext
 import viaduct.engine.runtime.execution.CompletionErrors.FieldCompletionException
 import viaduct.engine.runtime.execution.FieldExecutionHelpers.buildDataFetchingEnvironment
 import viaduct.engine.runtime.execution.FieldExecutionHelpers.buildOERKeyForField
@@ -139,7 +138,7 @@ class FieldCompleter(
                 // Handle fetch errors gracefully
                 handleFetchingException(dataFetchingEnvironmentProvider, throwable)
                     .map {
-                        FieldResolutionResult(null, it.errors, CompositeLocalContext.empty, emptyMap(), null)
+                        FieldResolutionResult.fromErrors(it.errors)
                     }
             }
 

engine/runtime/src/main/kotlin/viaduct/engine/runtime/execution/FieldExecutionHelpers.kt

@@ -152,7 +152,8 @@ object FieldExecutionHelpers {
         val engineExecCtx = parameters.executionContext.findLocalContextForType<EngineExecutionContextImpl>()
         val fieldScope = EngineExecutionContextImpl.FieldExecutionScopeImpl(
             fragments = parameters.queryPlan.fragments.map.mapValues { it.value.gjDef },
-            variables = parameters.coercedVariables.toMap()
+            variables = parameters.coercedVariables.toMap(),
+            resolutionPolicy = parameters.resolutionPolicy
         )
         val updatedEngineExecCtx = engineExecCtx.copy(fieldScope = fieldScope)
 

engine/runtime/src/main/kotlin/viaduct/engine/runtime/execution/FieldResolver.kt

@@ -28,6 +28,8 @@ import viaduct.deferred.asDeferred
 import viaduct.engine.api.CheckerResult
 import viaduct.engine.api.LazyEngineObjectData
 import viaduct.engine.api.ObjectEngineResult
+import viaduct.engine.api.ParentManagedValue
+import viaduct.engine.api.ResolutionPolicy
 import viaduct.engine.api.engineExecutionContext
 import viaduct.engine.runtime.Cell
 import viaduct.engine.runtime.EngineExecutionContextImpl
@@ -270,7 +272,7 @@ class FieldResolver(
             val (dataFetcherValue, fieldCheckerResultValue) = fetchField(field, parameters, dataFetchingEnvironmentProvider)
             val result = dataFetcherValue
                 .map { fv ->
-                    buildFieldResolutionResult(parameters, fieldType, fv)
+                    buildFieldResolutionResult(parameters, fieldType, fv, parameters.resolutionPolicy)
                 }.recover { e ->
                     // handle any errors that occurred during building FieldResolutionResult
                     val wrappedException = when (e) {
@@ -347,20 +349,34 @@ class FieldResolver(
         parameters: ExecutionParameters,
         fieldType: GraphQLOutputType,
         fetchedValue: FetchedValue,
+        resolutionPolicy: ResolutionPolicy,
     ): FieldResolutionResult {
         val field = checkNotNull(parameters.field) { "Expected parameters.field to be non-null." }
-        val data = fetchedValue.fetchedValue ?: return FieldResolutionResult.fromFetchedValue(null, fetchedValue)
+        val data = fetchedValue.fetchedValue ?: return FieldResolutionResult.fromFetchedValue(null, fetchedValue, resolutionPolicy)
+
+        // Unwrap data from "ParentManagedValue" if necessary, and set the effective resolution policy
+        var effectiveResolutionPolicy = resolutionPolicy
+        val effectiveData = if (data is ParentManagedValue) {
+            effectiveResolutionPolicy = ResolutionPolicy.PARENT_MANAGED
+            data.value
+        } else {
+            data
+        }
+
+        if (effectiveData == null) {
+            return FieldResolutionResult.fromFetchedValue(null, fetchedValue, effectiveResolutionPolicy)
+        }
 
         // if the type has a non-null wrapper, unwrap one level and recurse
         if (GraphQLTypeUtil.isNonNull(fieldType)) {
-            return buildFieldResolutionResult(parameters, GraphQLTypeUtil.unwrapNonNullAs(fieldType), fetchedValue)
+            return buildFieldResolutionResult(parameters, GraphQLTypeUtil.unwrapNonNullAs(fieldType), fetchedValue, effectiveResolutionPolicy)
         }
 
         // When it's a list, wrap each item in the list
         if (GraphQLTypeUtil.isList(fieldType)) {
             val newFieldType = GraphQLTypeUtil.unwrapOneAs<GraphQLOutputType>(fieldType)
-            val resultIterable = checkNotNull(data as? Iterable<*>) {
-                "Expected data to be an Iterable, was ${data.javaClass}."
+            val resultIterable = checkNotNull(effectiveData as? Iterable<*>) {
+                "Expected data to be an Iterable, was ${effectiveData.javaClass}."
             }
             return FieldResolutionResult.fromFetchedValue(
                 resultIterable.mapIndexed { index, it ->
@@ -370,7 +386,8 @@ class FieldResolver(
                         val itemFieldResolutionResult = buildFieldResolutionResult(
                             parameters,
                             newFieldType,
-                            itemFV
+                            itemFV,
+                            effectiveResolutionPolicy
                         )
                         slotSetter.setRawValue(Value.fromValue(itemFieldResolutionResult))
 
@@ -386,25 +403,27 @@ class FieldResolver(
                         slotSetter.setCheckerValue(typeCheckerResult)
                     }
                 },
-                fetchedValue
+                fetchedValue,
+                effectiveResolutionPolicy,
+                originalSource = effectiveData,
             )
         }
 
         // When it's a leaf value, it doesn't need wrapping
         if (GraphQLTypeUtil.isLeaf(fieldType)) {
-            return FieldResolutionResult.fromFetchedValue(data, fetchedValue)
+            return FieldResolutionResult.fromFetchedValue(effectiveData, fetchedValue, effectiveResolutionPolicy, originalSource = effectiveData)
         }
         // Interface or union type, resolve the type and wrap it
         if (GraphQLTypeUtil.isInterfaceOrUnion(fieldType)) {
             val resolvedType = typeResolver.resolveType(
                 parameters.executionContext,
                 field.mergedField,
-                data,
+                effectiveData,
                 parameters.executionStepInfo,
                 fieldType,
                 fetchedValue.localContext
             )
-            return buildFieldResolutionResult(parameters, resolvedType, fetchedValue)
+            return buildFieldResolutionResult(parameters, resolvedType, fetchedValue, effectiveResolutionPolicy)
         }
         // When it's an object, wrap the whole thing
         if (GraphQLTypeUtil.isObjectType(fieldType)) {
@@ -413,7 +432,7 @@ class FieldResolver(
             } else {
                 ObjectEngineResultImpl.newForType(fieldType as GraphQLObjectType)
             }
-            return FieldResolutionResult.fromFetchedValue(oer, fetchedValue)
+            return FieldResolutionResult.fromFetchedValue(oer, fetchedValue, effectiveResolutionPolicy, originalSource = effectiveData)
         }
         throw IllegalStateException("ObjectEngineResult must wrap a GraphQLObjectType.")
     }
@@ -522,7 +541,7 @@ class FieldResolver(
                 val oer = fieldResolutionResult.engineResult as? ObjectEngineResultImpl ?: return
                 fetchObject(
                     oer.graphQLObjectType,
-                    parameters.forObjectTraversal(field, oer, fieldResolutionResult.localContext, fieldResolutionResult.originalSource)
+                    parameters.forObjectTraversal(field, oer, fieldResolutionResult.localContext, fieldResolutionResult.originalSource, fieldResolutionResult.resolutionPolicy)
                 )
             }
         }

engine/runtime/src/main/kotlin/viaduct/engine/runtime/instrumentation/ResolverDataFetcherInstrumentation.kt

@@ -6,7 +6,10 @@ import graphql.schema.DataFetcher
 import viaduct.engine.api.FieldCheckerDispatcherRegistry
 import viaduct.engine.api.FieldResolverDispatcher
 import viaduct.engine.api.FieldResolverDispatcherRegistry
+import viaduct.engine.api.ResolutionPolicy
+import viaduct.engine.api.ViaductDataFetchingEnvironment
 import viaduct.engine.api.coroutines.CoroutineInterop
+import viaduct.engine.api.engineExecutionContext
 import viaduct.engine.api.instrumentation.ViaductModernGJInstrumentation
 import viaduct.engine.runtime.execution.DefaultCoroutineInterop
 import viaduct.engine.runtime.execution.ResolverDataFetcher
@@ -25,7 +28,13 @@ class ResolverDataFetcherInstrumentation(
         parameters: InstrumentationFieldFetchParameters,
         state: InstrumentationState?
     ): DataFetcher<*> {
-        val dfEnv = parameters.environment
+        val dfEnv = parameters.environment as ViaductDataFetchingEnvironment
+
+        val resolutionPolicy = dfEnv.engineExecutionContext.fieldScope.resolutionPolicy
+        if (resolutionPolicy == ResolutionPolicy.PARENT_MANAGED) {
+            return dataFetcher
+        }
+
         val typeName = dfEnv.parentType.asNamedElement().name
         val fieldName = dfEnv.fieldDefinition.name