Add input/output type context splitting to mutation engine

Operations automatically propagate input context to parameters and
output context to return types via GraphQLMutationOptions. The
framework's cache and options propagation handle nested types, so the
same source model produces separate input and output mutations without
any custom type-graph walking.

Author: FionaBronwen

packages/graphql/src/mutation-engine/engine.ts

@@ -24,6 +24,7 @@ import {
   GraphQLScalarMutation,
   GraphQLUnionMutation,
 } from "./mutations/index.js";
+import { GraphQLMutationOptions, GraphQLTypeContext } from "./options.js";
 
 /**
  * Registry configuration for the GraphQL mutation engine.
@@ -49,7 +50,12 @@ const graphqlMutationRegistry = {
 
 /**
  * GraphQL mutation engine that applies GraphQL-specific transformations
- * to TypeSpec types, such as name sanitization.
+ * to TypeSpec types, such as name sanitization, scalar mapping, and
+ * input/output type splitting via mutation keys.
+ *
+ * When an operation is mutated, parameters are automatically mutated with
+ * input context and return types with output context. The mutation framework's
+ * cache ensures each (type, context) pair produces a separate mutation.
  */
 export class GraphQLMutationEngine {
   /**
@@ -70,6 +76,15 @@ export class GraphQLMutationEngine {
     return this.engine.mutate(model, new SimpleMutationOptions()) as GraphQLModelMutation;
   }
 
+  /**
+   * Mutate a model with explicit input/output context.
+   * Models mutated with different contexts produce separate cached mutations,
+   * allowing the same source model to have both an input and output variant.
+   */
+  mutateModelAs(model: Model, context: GraphQLTypeContext): GraphQLModelMutation {
+    return this.engine.mutate(model, new GraphQLMutationOptions(context)) as GraphQLModelMutation;
+  }
+
   /**
    * Mutate an enum, applying GraphQL name sanitization.
    */
@@ -79,6 +94,8 @@ export class GraphQLMutationEngine {
 
   /**
    * Mutate an operation, applying GraphQL name sanitization.
+   * Parameters are automatically mutated with input context,
+   * return types with output context.
    */
   mutateOperation(operation: Operation): GraphQLOperationMutation {
     return this.engine.mutate(operation, new SimpleMutationOptions()) as GraphQLOperationMutation;

packages/graphql/src/mutation-engine/index.ts

@@ -1,4 +1,5 @@
 export { GraphQLMutationEngine, createGraphQLMutationEngine } from "./engine.js";
+export { GraphQLMutationOptions, GraphQLTypeContext } from "./options.js";
 export {
   GraphQLEnumMemberMutation,
   GraphQLEnumMutation,

packages/graphql/src/mutation-engine/mutations/model.ts

@@ -7,6 +7,7 @@ import {
   type SimpleMutations,
 } from "@typespec/mutator-framework";
 import { sanitizeNameForGraphQL } from "../../lib/type-utils.js";
+import { GraphQLMutationOptions, GraphQLTypeContext } from "../options.js";
 
 /**
  * GraphQL-specific Model mutation.
@@ -22,6 +23,16 @@ export class GraphQLModelMutation extends SimpleModelMutation<SimpleMutationOpti
     super(engine, sourceType, referenceTypes, options, info);
   }
 
+  /**
+   * The input/output context this model was mutated with, if any.
+   * Undefined when the model was mutated directly (not through an operation).
+   */
+  get typeContext(): GraphQLTypeContext | undefined {
+    return this.options instanceof GraphQLMutationOptions
+      ? this.options.typeContext
+      : undefined;
+  }
+
   mutate() {
     // Apply GraphQL name sanitization
     this.mutationNode.mutate((model) => {

packages/graphql/src/mutation-engine/mutations/operation.ts

@@ -7,6 +7,7 @@ import {
   type SimpleMutations,
 } from "@typespec/mutator-framework";
 import { sanitizeNameForGraphQL } from "../../lib/type-utils.js";
+import { GraphQLMutationOptions, GraphQLTypeContext } from "../options.js";
 
 /** GraphQL-specific Operation mutation. */
 export class GraphQLOperationMutation extends SimpleOperationMutation<SimpleMutationOptions> {
@@ -20,6 +21,32 @@ export class GraphQLOperationMutation extends SimpleOperationMutation<SimpleMuta
     super(engine, sourceType, referenceTypes, options, info);
   }
 
+  /**
+   * Override to mutate parameters with input context.
+   * Types reachable from operation parameters become GraphQL input types.
+   */
+  protected override mutateParameters() {
+    const inputOptions = new GraphQLMutationOptions(GraphQLTypeContext.Input);
+    this.parameters = this.engine.mutate(
+      this.sourceType.parameters,
+      inputOptions,
+      this.startParametersEdge(),
+    );
+  }
+
+  /**
+   * Override to mutate return type with output context.
+   * Types reachable from operation return types become GraphQL object types.
+   */
+  protected override mutateReturnType() {
+    const outputOptions = new GraphQLMutationOptions(GraphQLTypeContext.Output);
+    this.returnType = this.engine.mutate(
+      this.sourceType.returnType,
+      outputOptions,
+      this.startReturnTypeEdge(),
+    );
+  }
+
   mutate() {
     // Apply GraphQL name sanitization via callback
     this.mutationNode.mutate((operation) => {

packages/graphql/src/mutation-engine/mutations/union.ts

@@ -140,16 +140,22 @@ export class GraphQLUnionMutation extends UnionMutation<MutationOptions, any, Mu
    * GraphQL doesn't support nested unions, so union Pet { cat: Cat, animal: Animal }
    * where Animal is itself a union becomes union Pet { Cat | Bear | Lion }
    */
-  private flattenUnionVariants(union: Union): Array<{ name: string | symbol; type: Type }> {
+  private flattenUnionVariants(
+    union: Union,
+    seen: Set<Union> = new Set(),
+  ): Array<{ name: string | symbol; type: Type }> {
+    if (seen.has(union)) {
+      return [];
+    }
+    seen.add(union);
+
     const flattened: Array<{ name: string | symbol; type: Type }> = [];
 
     for (const variant of union.variants.values()) {
       if (variant.type.kind === "Union") {
-        // Recursively flatten nested union
-        const nestedVariants = this.flattenUnionVariants(variant.type as Union);
+        const nestedVariants = this.flattenUnionVariants(variant.type as Union, seen);
         flattened.push(...nestedVariants);
       } else {
-        // Regular variant (not a union)
         flattened.push({ name: variant.name, type: variant.type });
       }
     }

packages/graphql/src/mutation-engine/options.ts

@@ -0,0 +1,30 @@
+import { SimpleMutationOptions } from "@typespec/mutator-framework";
+
+/**
+ * Context for how a type is used in GraphQL operations.
+ * Determines whether a model becomes an object type (output) or input type (input).
+ */
+export enum GraphQLTypeContext {
+  /** Type reachable from operation parameters */
+  Input = "input",
+  /** Type reachable from operation return types */
+  Output = "output",
+}
+
+/**
+ * Mutation options that carry input/output context through the type graph.
+ * The mutationKey ensures the framework caches input and output variants
+ * separately for the same source type.
+ */
+export class GraphQLMutationOptions extends SimpleMutationOptions {
+  readonly typeContext: GraphQLTypeContext;
+
+  constructor(typeContext: GraphQLTypeContext) {
+    super();
+    this.typeContext = typeContext;
+  }
+
+  override get mutationKey(): string {
+    return this.typeContext;
+  }
+}