@salesforce/graphiti 10.10.2

package/src/intent/__tests__/build-mutation.spec.ts

@@ -0,0 +1,108 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import { buildSchema } from "graphql";
+import { describe, expect, it, vi } from "vitest";
+import { makeNoopPrimeDeps } from "../../__tests__/helpers/prime-deps.js";
+import * as sessionModule from "../../lib/session.js";
+import { primeSchemaCache } from "../../lib/walker.js";
+import { buildMutation } from "../build-mutation.js";
+
+vi.mock("../../lib/session.js", async (importOriginal) => {
+	const actual = await importOriginal<typeof sessionModule>();
+	return { ...actual, createSession: vi.fn(actual.createSession) };
+});
+
+const SCHEMA_SDL = `
+	type Query { _placeholder: Boolean }
+	type Mutation { uiapi(input: UIAPIMutationsInput): UIAPIMutations! }
+	input UIAPIMutationsInput { allOrNone: Boolean }
+	type UIAPIMutations {
+		AccountCreate(input: AccountCreateInput!): AccountCreatePayload
+		AccountUpdate(input: AccountUpdateInput!): AccountUpdatePayload
+	}
+	input AccountCreateInput { Account: AccountCreateRepresentation! }
+	input AccountCreateRepresentation { Name: String }
+	type AccountCreatePayload { Record: Account }
+	input AccountUpdateInput { Account: AccountUpdateRepresentation! }
+	input AccountUpdateRepresentation { Name: String }
+	type AccountUpdatePayload { Record: Account }
+	type Account { Id: ID!, Name: StringValue }
+	type StringValue { value: String }
+`;
+
+const ORG = "test-build-mutation";
+const ORG_URL = "https://test-build-mutation.my.salesforce.com";
+const SCHEMA = buildSchema(SCHEMA_SDL);
+primeSchemaCache(ORG, SCHEMA);
+primeSchemaCache(ORG_URL, SCHEMA);
+
+const noopPrimeDeps = () => makeNoopPrimeDeps(ORG, ORG_URL, SCHEMA);
+
+describe("intent/build-mutation", () => {
+	it("op=Create renders mutation Create<Object> with <Object>CreateInput!", async () => {
+		const result = await buildMutation(
+			{ org: ORG, object: "Account", returnFields: ["Id", "Name"] },
+			"Create",
+			noopPrimeDeps(),
+		);
+		expect(result.query).toMatch(/mutation CreateAccount/);
+		expect(result.query).toMatch(/\$input:\s*AccountCreateInput!/);
+		expect(result.query).toMatch(/AccountCreate\(input:\s*\$input\)/);
+		expect(result.query).toMatch(/Name\s*\{\s*value/s);
+		expect(result.variables).toEqual([
+			{ name: "input", type: "AccountCreateInput!", required: true },
+		]);
+	});
+
+	it("op=Update renders mutation Update<Object> with <Object>UpdateInput!", async () => {
+		const result = await buildMutation(
+			{ org: ORG, object: "Account", returnFields: ["Id", "Name"] },
+			"Update",
+			noopPrimeDeps(),
+		);
+		expect(result.query).toMatch(/mutation UpdateAccount/);
+		expect(result.query).toMatch(/\$input:\s*AccountUpdateInput!/);
+		expect(result.query).toMatch(/AccountUpdate\(input:\s*\$input\)/);
+		expect(result.query).toMatch(/Name\s*\{\s*value/s);
+		expect(result.variables).toEqual([
+			{ name: "input", type: "AccountUpdateInput!", required: true },
+		]);
+	});
+
+	it('op=Update defaults returnFields to ["Id"]', async () => {
+		const result = await buildMutation({ org: ORG, object: "Account" }, "Update", noopPrimeDeps());
+		expect(result.query).toMatch(/\bId\b/);
+		expect(result.query).not.toMatch(/Name\s*\{/);
+	});
+
+	it("op=Update with custom inputVariable strips leading $ and declares it", async () => {
+		const result = await buildMutation(
+			{ org: ORG, object: "Account", inputVariable: "$myInput" },
+			"Update",
+			noopPrimeDeps(),
+		);
+		expect(result.query).toMatch(/\$myInput:\s*AccountUpdateInput!/);
+		expect(result.query).toMatch(/input:\s*\$myInput/);
+		expect(result.query).not.toMatch(/\$\$myInput/);
+	});
+
+	it("op=Update with custom operationName uses it", async () => {
+		const result = await buildMutation(
+			{ org: ORG, object: "Account", operationName: "MutateAccount" },
+			"Update",
+			noopPrimeDeps(),
+		);
+		expect(result.query).toMatch(/mutation MutateAccount/);
+	});
+
+	it("threads instanceUrl as 3rd arg to createSession", async () => {
+		const spy = vi.mocked(sessionModule.createSession);
+		spy.mockClear();
+		await buildMutation({ org: ORG, object: "Account" }, "Update", noopPrimeDeps());
+		expect(spy).toHaveBeenCalledWith(ORG, "mutation", ORG_URL);
+	});
+});

package/src/intent/__tests__/build-output.spec.ts

@@ -0,0 +1,55 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import { buildSchema } from "graphql";
+import { describe, expect, it } from "vitest";
+import { createSession, selectLeaf } from "../../lib/session.js";
+import { buildOutput } from "../build-output.js";
+
+const schema = buildSchema(`
+	type Query { ping: String }
+`);
+
+describe("intent/build-output", () => {
+	it("renders query, no warnings on valid query", () => {
+		const session = createSession("test", "query");
+		selectLeaf(session, ["ping"]);
+		const out = buildOutput(session, schema);
+		expect(out.query).toMatch(/ping/);
+		expect(out.warnings).toEqual([]);
+		expect(typeof out.types).toBe("string");
+	});
+
+	it("threads priming note into warnings", () => {
+		const session = createSession("test", "query");
+		selectLeaf(session, ["ping"]);
+		const out = buildOutput(session, schema, 'Note: Primed schema cache for "a" (took 12ms)');
+		expect(out.warnings).toHaveLength(1);
+		expect(out.warnings[0]!).toMatch(/Primed schema cache/);
+	});
+
+	it("emits Validation: prefix for query-level errors", () => {
+		const session = createSession("test", "query");
+		selectLeaf(session, ["doesNotExist"]);
+		const out = buildOutput(session, schema);
+		expect(out.warnings.some((w) => w.startsWith("Validation:"))).toBe(true);
+	});
+
+	it("surfaces codegen failure as Codegen: warning + placeholder types", () => {
+		const session = createSession("test", "query");
+		selectLeaf(session, ["ping"]);
+		// Trigger: assign non-string values to session.id and session.name so that
+		// generateTypes' internal toPascalCase call throws. If codegen ever guards
+		// these reads with String(...), this trigger will stop firing and the test
+		// will fail loudly — replace the trigger with another path that makes
+		// generateTypes throw (e.g., an unsupported codegen language option).
+		(session as unknown as { id: unknown }).id = { broken: true };
+		(session as unknown as { name: unknown }).name = { broken: true };
+		const out = buildOutput(session, schema);
+		expect(out.types).toMatch(/\/\/ Type generation failed:/);
+		expect(out.warnings.some((w) => w.startsWith("Codegen:"))).toBe(true);
+	});
+});

package/src/intent/__tests__/build-raw.spec.ts

@@ -0,0 +1,153 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import { buildSchema } from "graphql";
+import { describe, expect, it, vi } from "vitest";
+import { makeNoopPrimeDeps } from "../../__tests__/helpers/prime-deps.js";
+import * as sessionModule from "../../lib/session.js";
+import { primeSchemaCache } from "../../lib/walker.js";
+import { buildRaw } from "../build-raw.js";
+
+vi.mock("../../lib/session.js", async (importOriginal) => {
+	const actual = await importOriginal<typeof sessionModule>();
+	return { ...actual, createSession: vi.fn(actual.createSession) };
+});
+
+const SCHEMA_SDL = `
+	type Query { uiapi: UIAPI! }
+	type UIAPI { query: RecordQuery!, aggregate: RecordQueryAggregate! }
+	type RecordQuery {
+		Case(first: Int, after: String, where: Case_Filter): CaseConnection!
+	}
+	type RecordQueryAggregate {
+		Case(first: Int, where: Case_Filter, groupBy: Case_GroupBy): CaseAggregateConnection
+	}
+	input Case_Filter { Status: PicklistOperators }
+	input Case_GroupBy { Status: GroupByClause }
+	input GroupByClause { group: Boolean }
+	input PicklistOperators { eq: String }
+	type CaseConnection { edges: [CaseEdge!]!, pageInfo: PageInfo! }
+	type CaseEdge { node: Case! }
+	type CaseAggregateConnection { edges: [CaseAggregateEdge!]!, pageInfo: PageInfo! }
+	type CaseAggregateEdge { node: CaseResult! }
+	type CaseResult { aggregate: CaseAggregate }
+	type CaseAggregate { Id: IDAggregate }
+	type IDAggregate { count: Int }
+	type PageInfo { hasNextPage: Boolean!, endCursor: String }
+	type Case { Id: ID!, Subject: StringValue, Status: StringValue }
+	type StringValue { value: String }
+
+	type Mutation { uiapi: UIAPIMut! }
+	type UIAPIMut { placeholder: Boolean }
+`;
+
+const ORG = "test-raw";
+const ORG_URL = "https://test-raw.my.salesforce.com";
+const SCHEMA = buildSchema(SCHEMA_SDL);
+primeSchemaCache(ORG, SCHEMA);
+primeSchemaCache(ORG_URL, SCHEMA);
+const deps = () => makeNoopPrimeDeps(ORG, ORG_URL, SCHEMA);
+
+describe("intent/build-raw", () => {
+	it("renders a query from select + set commands", async () => {
+		const out = await buildRaw(
+			{
+				org: ORG,
+				commands: [
+					"select uiapi/query/Case/edges/node/Subject/value",
+					"set uiapi/query/Case first=5",
+				],
+			},
+			deps(),
+		);
+		expect(out.query).toMatch(/Subject\s*\{\s*value\s*\}/);
+		expect(out.query).toMatch(/first:\s*5/);
+		expect(out.query).toMatch(/\bquery\b/);
+	});
+
+	it("uses the mutation root when operation is mutation", async () => {
+		const out = await buildRaw(
+			{ org: ORG, commands: ["select uiapi/placeholder"], operation: "mutation" },
+			deps(),
+		);
+		expect(out.query).toMatch(/\bmutation\b/);
+	});
+
+	it("uses the aggregate root when operation is aggregate", async () => {
+		const out = await buildRaw(
+			{
+				org: ORG,
+				commands: ["select uiapi/aggregate/Case/edges/node/aggregate/Id/count"],
+				operation: "aggregate",
+			},
+			deps(),
+		);
+		// Aggregate operations render under the query keyword against uiapi.aggregate.
+		expect(out.query).toMatch(/\bquery\s+RawAggregate\b/);
+		expect(out.query).toMatch(/aggregate\s*\{[\s\S]*Id\s*\{[\s\S]*count/);
+	});
+
+	it("honors typeName as the operation name", async () => {
+		const out = await buildRaw(
+			{ org: ORG, commands: ["select uiapi/query/Case/edges/node/Id"], typeName: "MyRaw" },
+			deps(),
+		);
+		expect(out.query).toMatch(/\bquery\s+MyRaw\b/);
+	});
+
+	it("defaults operation name to RawQuery", async () => {
+		const out = await buildRaw(
+			{ org: ORG, commands: ["select uiapi/query/Case/edges/node/Id"] },
+			deps(),
+		);
+		expect(out.query).toMatch(/\bquery\s+RawQuery\b/);
+	});
+
+	it("fails fast: a bad command throws with its index and text", async () => {
+		await expect(
+			buildRaw(
+				{
+					org: ORG,
+					commands: ["select uiapi/query/Case/edges/node/Id", "frobnicate the widget"],
+				},
+				deps(),
+			),
+		).rejects.toThrow(/command 1 \(frobnicate the widget\).*unknown command 'frobnicate'/s);
+	});
+
+	it("rejects an empty commands array", async () => {
+		await expect(buildRaw({ org: ORG, commands: [] }, deps())).rejects.toThrow(
+			/at least one command/,
+		);
+	});
+
+	it("returns a ToolOutput with the standard shape", async () => {
+		const out = await buildRaw(
+			{ org: ORG, commands: ["select uiapi/query/Case/edges/node/Id"] },
+			deps(),
+		);
+		expect(out).toHaveProperty("query");
+		expect(out).toHaveProperty("variables");
+		expect(out).toHaveProperty("types");
+		expect(Array.isArray(out.warnings)).toBe(true);
+	});
+
+	it("rejects a typeName that is not a valid GraphQL Name", async () => {
+		await expect(
+			buildRaw(
+				{ org: ORG, commands: ["select uiapi/query/Case/edges/node/Id"], typeName: "has spaces" },
+				deps(),
+			),
+		).rejects.toThrow(/buildRaw: typeName 'has spaces' is not a valid GraphQL Name/);
+	});
+
+	it("threads instanceUrl as 3rd arg to createSession", async () => {
+		const spy = vi.mocked(sessionModule.createSession);
+		spy.mockClear();
+		await buildRaw({ org: ORG, commands: ["select uiapi/query/Case/edges/node/Id"] }, deps());
+		expect(spy).toHaveBeenCalledWith(ORG, "query", ORG_URL);
+	});
+});

package/src/intent/__tests__/build-update-validation.spec.ts

@@ -0,0 +1,134 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import { buildSchema } from "graphql";
+import { describe, expect, it } from "vitest";
+import { makeNoopPrimeDeps } from "../../__tests__/helpers/prime-deps.js";
+import { primeSchemaCache } from "../../lib/walker.js";
+import { buildUpdate } from "../build-update.js";
+
+const SCHEMA_SDL = `
+	type Query { _placeholder: Boolean }
+	type Mutation { uiapi(input: UIAPIMutationsInput): UIAPIMutations! }
+	input UIAPIMutationsInput { allOrNone: Boolean }
+	type UIAPIMutations {
+		AccountUpdate(input: AccountUpdateInput!): AccountUpdatePayload
+		Custom_Object__cUpdate(input: Custom_Object__cUpdateInput!): Custom_Object__cUpdatePayload
+	}
+	input AccountUpdateInput { Account: AccountUpdateRepresentation! }
+	input AccountUpdateRepresentation { Name: String, Industry: String }
+	type AccountUpdatePayload { Record: Account }
+	input Custom_Object__cUpdateInput { Custom_Object__c: Custom_Object__cUpdateRepresentation! }
+	input Custom_Object__cUpdateRepresentation { Name: String }
+	type Custom_Object__cUpdatePayload { Record: Custom_Object__c }
+	type Account { Id: ID!, Name: StringValue, Industry: StringValue }
+	type Custom_Object__c { Id: ID!, Name: StringValue }
+	type StringValue { value: String }
+`;
+
+const ORG = "test-update-validation";
+const ORG_URL = "https://test-update-validation.my.salesforce.com";
+const SCHEMA = buildSchema(SCHEMA_SDL);
+primeSchemaCache(ORG, SCHEMA);
+primeSchemaCache(ORG_URL, SCHEMA);
+
+const noopPrimeDeps = () => makeNoopPrimeDeps(ORG, ORG_URL, SCHEMA);
+
+describe("intent/build-update — GraphQL name validation", () => {
+	describe("object name validation", () => {
+		it("throws for object with special characters: 'not valid!'", async () => {
+			await expect(
+				buildUpdate({ org: ORG, object: "not valid!" }, noopPrimeDeps()),
+			).rejects.toThrow(/buildMutation: object 'not valid!' is not a valid GraphQL Name/);
+		});
+
+		it("throws for object starting with a digit: '123Object'", async () => {
+			await expect(buildUpdate({ org: ORG, object: "123Object" }, noopPrimeDeps())).rejects.toThrow(
+				/buildMutation: object '123Object' is not a valid GraphQL Name/,
+			);
+		});
+
+		it("throws for object with hyphens: 'my-object'", async () => {
+			await expect(buildUpdate({ org: ORG, object: "my-object" }, noopPrimeDeps())).rejects.toThrow(
+				/buildMutation: object 'my-object' is not a valid GraphQL Name/,
+			);
+		});
+
+		it("accepts valid object name with underscores: 'Custom_Object__c'", async () => {
+			const result = await buildUpdate(
+				{ org: ORG, object: "Custom_Object__c", returnFields: ["Id"] },
+				noopPrimeDeps(),
+			);
+			expect(result.query).toContain("Custom_Object__cUpdate");
+		});
+
+		it("accepts standard object name: 'Account'", async () => {
+			const result = await buildUpdate(
+				{ org: ORG, object: "Account", returnFields: ["Id"] },
+				noopPrimeDeps(),
+			);
+			expect(result.query).toContain("mutation UpdateAccount");
+		});
+
+		it("accepts object starting with underscore: '_Foo'", async () => {
+			// The regex allows underscore as first char per GraphQL spec.
+			await expect(
+				buildUpdate({ org: ORG, object: "_Foo" }, noopPrimeDeps()),
+			).resolves.toBeDefined();
+		});
+	});
+
+	describe("inputVariable name validation", () => {
+		it("throws for inputVariable with spaces: 'has spaces'", async () => {
+			await expect(
+				buildUpdate({ org: ORG, object: "Account", inputVariable: "has spaces" }, noopPrimeDeps()),
+			).rejects.toThrow(/buildMutation: inputVariable 'has spaces' is not a valid GraphQL Name/);
+		});
+
+		it("throws for inputVariable with dollar sign in body: 'my$var'", async () => {
+			await expect(
+				buildUpdate({ org: ORG, object: "Account", inputVariable: "my$var" }, noopPrimeDeps()),
+			).rejects.toThrow(/buildMutation: inputVariable 'my\$var' is not a valid GraphQL Name/);
+		});
+
+		it("throws for inputVariable starting with digit: '1input'", async () => {
+			await expect(
+				buildUpdate({ org: ORG, object: "Account", inputVariable: "1input" }, noopPrimeDeps()),
+			).rejects.toThrow(/buildMutation: inputVariable '1input' is not a valid GraphQL Name/);
+		});
+
+		it("accepts inputVariable with leading $ (prefix stripped): '$myInput'", async () => {
+			const result = await buildUpdate(
+				{ org: ORG, object: "Account", inputVariable: "$myInput" },
+				noopPrimeDeps(),
+			);
+			expect(result.query).toContain("$myInput");
+		});
+
+		it("accepts valid inputVariable: 'accountInput'", async () => {
+			const result = await buildUpdate(
+				{ org: ORG, object: "Account", inputVariable: "accountInput" },
+				noopPrimeDeps(),
+			);
+			expect(result.query).toContain("$accountInput");
+		});
+
+		it("accepts default inputVariable 'input' when not specified", async () => {
+			const result = await buildUpdate({ org: ORG, object: "Account" }, noopPrimeDeps());
+			expect(result.query).toContain("$input");
+		});
+	});
+
+	describe("operationName name validation", () => {
+		// Exhaustive name matrix lives in lib/__tests__/graphql-name.spec.ts; this
+		// just asserts buildMutation wires operationName through the guard.
+		it("throws for an operationName that is not a valid GraphQL Name", async () => {
+			await expect(
+				buildUpdate({ org: ORG, object: "Account", operationName: "has spaces" }, noopPrimeDeps()),
+			).rejects.toThrow(/buildMutation: operationName 'has spaces' is not a valid GraphQL Name/);
+		});
+	});
+});

package/src/intent/build-aggregate.ts

@@ -0,0 +1,182 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import { buildOutput } from "./build-output.js";
+import { getSchemaWithPriming } from "./get-schema-with-priming.js";
+import {
+	type AggregateSpec,
+	type AggregationSpec,
+	type GroupByElement,
+	type ToolOutput,
+} from "./types.js";
+import { assertGraphqlName } from "../lib/graphql-name.js";
+import { type PrimeDeps } from "../lib/prime-schema.js";
+import {
+	addVariable,
+	createSession,
+	createSiblingFieldInstance,
+	deepSetArg,
+	type QuerySession,
+	selectLeaf,
+} from "../lib/session.js";
+import { aggregatePath } from "../lib/uiapi.js";
+import { normalizeOrderBy, promoteVariables } from "../lib/variable-promotion.js";
+
+const FIELD_REQUIRED_FNS = new Set<AggregationSpec["function"]>(["sum", "avg", "min", "max"]);
+
+/**
+ * Build a UIAPI aggregate query against a Salesforce org. Implements
+ * `sf_gql_aggregate` intent for the graphiti MCP server (FR-8).
+ *
+ * Implicit behaviors not visible in the signature:
+ * - `aggregations[]` projects each entry under the SObject's aggregate node
+ *   using `<function><PascalCaseField>` as the default GraphQL alias; pass
+ *   `alias` to override. Default field is `Id` for `count`/`countDistinct`;
+ *   `sum`/`avg`/`min`/`max` require a field (FR-8.3).
+ * - Duplicate result keys (default or explicit) throw — the caller must
+ *   disambiguate with aliases (FR-8.4).
+ * - `groupBy` accepts flat field names only in v1; each renders as
+ *   `{Field: {group: true}}` and selects `Field { value }` on the
+ *   aggregate node so the grouping leaf comes back in the response.
+ *   Dotted paths throw.
+ * - `filter` applies to every aggregation in the call. `$varName` leaves
+ *   in the filter promote to typed query variables. Per-aggregation
+ *   filters are not supported (FR-8.6).
+ * - Operation name defaults to `<Object>Aggregate`.
+ *
+ * Throws on invalid `object` or `operationName` (must be valid GraphQL Names),
+ * auth-missing or introspection failure (via `getSchemaWithPriming`), on
+ * FR-8.3/8.4 spec violations, and on dotted groupBy paths. Never throws on
+ * validation or codegen failure (those surface as `warnings[]`).
+ */
+export async function buildAggregate(spec: AggregateSpec, deps?: PrimeDeps): Promise<ToolOutput> {
+	assertGraphqlName(spec.object, "buildAggregate", "object");
+
+	const { schema, primingNote, instanceUrl } = await getSchemaWithPriming(spec.org, deps);
+
+	const session = createSession(spec.org, "aggregate", instanceUrl);
+	session.operationName = spec.operationName ?? `${spec.object}Aggregate`;
+	assertGraphqlName(session.operationName, "buildAggregate", "operationName");
+
+	const connectionPath = aggregatePath(spec.object);
+	const aggregateNodePath = [...connectionPath, "edges", "node", "aggregate"];
+
+	const groupBy = spec.groupBy ?? [];
+	const extraWarnings: string[] = [];
+	applyGroupBy(session, connectionPath, aggregateNodePath, groupBy);
+
+	if (spec.filter) {
+		promoteVariables(session, schema, connectionPath, "where", spec.filter, extraWarnings);
+		deepSetArg(session, connectionPath, "where", [], JSON.stringify(spec.filter));
+	}
+
+	const orderBy = normalizeOrderBy(spec.orderBy);
+	if (Array.isArray(spec.orderBy) && spec.orderBy.length > 1) {
+		extraWarnings.push(
+			"orderBy: array collapsed to first element. UIAPI accepts a single orderBy object — use multiple keys in one object for multi-field ordering (e.g. { Industry: { order: DESC }, Name: { order: ASC } }).",
+		);
+	}
+	if (orderBy) {
+		promoteVariables(session, schema, connectionPath, "orderBy", orderBy, extraWarnings);
+		deepSetArg(session, connectionPath, "orderBy", [], JSON.stringify(orderBy));
+	}
+
+	if (spec.first !== undefined) {
+		deepSetArg(session, connectionPath, "first", [], String(spec.first));
+	}
+
+	addVariable(session, "after", "String");
+	deepSetArg(session, connectionPath, "after", [], "$after");
+
+	selectLeaf(session, [...connectionPath, "pageInfo", "hasNextPage"]);
+	selectLeaf(session, [...connectionPath, "pageInfo", "endCursor"]);
+
+	// FR-8.2 — `aggregate(Account)` with no aggregations and no groupBy
+	// defaults to `count` over `Id` (the SOQL `select count(*)` analogue).
+	const requested = spec.aggregations ?? [];
+	const aggregations: AggregationSpec[] =
+		requested.length === 0 && groupBy.length === 0 ? [{ function: "count" }] : requested;
+
+	// Pre-seed with groupBy field names: each renders as a top-level response
+	// key on the aggregate node alongside aggregation aliases. An aggregation
+	// alias colliding with a groupBy key produces invalid GraphQL (different
+	// shapes, same response key — spec §5.3.2).
+	const seenKeys = new Set<string>(groupBy.map((el) => (typeof el === "string" ? el : el.field)));
+	for (const agg of aggregations) {
+		if (agg.field === undefined && FIELD_REQUIRED_FNS.has(agg.function)) {
+			throw new Error(`buildAggregate: aggregation '${agg.function}' requires a field (FR-8.3)`);
+		}
+		if (agg.alias !== undefined) {
+			assertGraphqlName(agg.alias, "buildAggregate", "alias");
+		}
+		const field = agg.field ?? "Id";
+		const key = agg.alias ?? defaultKey(agg.function, field);
+		if (seenKeys.has(key)) {
+			throw new Error(
+				`buildAggregate: duplicate aggregation key '${key}' — set distinct aliases (FR-8.4)`,
+			);
+		}
+		seenKeys.add(key);
+		applyAggregation(session, aggregateNodePath, agg, field, key);
+	}
+
+	return buildOutput(session, schema, primingNote, extraWarnings);
+}
+
+function applyGroupBy(
+	session: QuerySession,
+	connectionPath: string[],
+	aggregateNodePath: string[],
+	groupBy: GroupByElement[],
+): void {
+	if (groupBy.length === 0) return;
+	const seenGroupByFields = new Set<string>();
+	for (const element of groupBy) {
+		const field = typeof element === "string" ? element : element.field;
+		if (seenGroupByFields.has(field)) {
+			throw new Error(`buildAggregate: duplicate groupBy field '${field}'`);
+		}
+		seenGroupByFields.add(field);
+		if (field.includes(".")) {
+			throw new Error(
+				`buildAggregate: dotted groupBy field '${field}' is not supported in v1 (flat-only)`,
+			);
+		}
+		assertGraphqlName(field, "buildAggregate", "groupBy field");
+		if (typeof element === "string") {
+			deepSetArg(session, connectionPath, "groupBy", [field, "group"], "true");
+		} else {
+			deepSetArg(session, connectionPath, "groupBy", [field, "function"], element.function);
+		}
+		selectLeaf(session, [...aggregateNodePath, field, "value"]);
+	}
+}
+
+function applyAggregation(
+	session: QuerySession,
+	aggregateNodePath: string[],
+	agg: AggregationSpec,
+	field: string,
+	key: string,
+): void {
+	const fieldPath = [...aggregateNodePath, field];
+	createSiblingFieldInstance(session, fieldPath, key);
+	selectLeaf(session, [...fieldPath, agg.function, "value"]);
+}
+
+function defaultKey(fn: string, field: string): string {
+	return `${fn}${pascalCase(field)}`;
+}
+
+function pascalCase(field: string): string {
+	const stripped = field.endsWith("__c") ? field.slice(0, -3) : field;
+	return stripped
+		.replace(/[^a-zA-Z0-9]/g, " ")
+		.split(/\s+/)
+		.filter(Boolean)
+		.map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+		.join("");
+}

package/src/intent/build-create.ts

@@ -0,0 +1,19 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import { buildMutation } from "./build-mutation.js";
+import { type CreateSpec, type ToolOutput } from "./types.js";
+import { type PrimeDeps } from "../lib/prime-schema.js";
+
+/**
+ * Build a UIAPI create mutation against a Salesforce org. Implements
+ * `sf_gql_create` intent for the graphiti MCP server (FR-5.6). Thin
+ * wrapper around `buildMutation` with `op = "Create"`; see that helper
+ * for behavior details.
+ */
+export async function buildCreate(spec: CreateSpec, deps?: PrimeDeps): Promise<ToolOutput> {
+	return buildMutation(spec, "Create", deps);
+}