@salesforce/graphiti 10.20.2 → 10.22.0

package/src/intent/build-aggregate.ts

@@ -68,6 +68,13 @@ export async function buildAggregate(spec: AggregateSpec, deps?: PrimeDeps): Pro
 	const extraWarnings: string[] = [];
 	applyGroupBy(session, connectionPath, aggregateNodePath, groupBy);
 
+	// Declare the reserved cursor variable before promoting user filter/orderBy
+	// variables, so a filter that reuses `$after` keeps its `String` type
+	// (first-wins) and surfaces a collision warning instead of overwriting the
+	// pagination arg's type (W-22697670). Mirrors buildList's ordering.
+	addVariable(session, "after", "String");
+	deepSetArg(session, connectionPath, "after", [], "$after");
+
 	if (spec.filter) {
 		promoteVariables(session, schema, connectionPath, "where", spec.filter, extraWarnings);
 		deepSetArg(session, connectionPath, "where", [], JSON.stringify(spec.filter));
@@ -88,9 +95,6 @@ export async function buildAggregate(spec: AggregateSpec, deps?: PrimeDeps): Pro
 		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"]);
 

package/src/intent/build-detail.ts

@@ -63,9 +63,11 @@ export async function buildDetail(spec: DetailSpec, deps?: PrimeDeps): Promise<T
 		}
 	}
 
+	const extraWarnings: string[] = [];
+
 	if (spec.childRelationships) {
 		for (const child of spec.childRelationships) {
-			selectChildRelationship(session, schema, node, child);
+			selectChildRelationship(session, schema, node, child, extraWarnings);
 		}
 	}
 
@@ -91,5 +93,5 @@ export async function buildDetail(spec: DetailSpec, deps?: PrimeDeps): Promise<T
 	deepSetArg(session, connection, "where", ["Id", "eq"], `$${idVar}`);
 	deepSetArg(session, connection, "first", [], "1");
 
-	return buildOutput(session, schema, primingNote);
+	return buildOutput(session, schema, primingNote, extraWarnings);
 }

package/src/intent/build-list.ts

@@ -56,36 +56,41 @@ export async function buildList(spec: ListSpec, deps?: PrimeDeps): Promise<ToolO
 		}
 	}
 
+	const extraWarnings: string[] = [];
+
+	// Declare the reserved cursor variable before promoting ANY user variables —
+	// including childRelationship filters — so a filter reusing $after keeps String
+	// (first-wins) and warns, instead of overwriting the pagination arg's type (W-22697670).
+	addVariable(session, "after", "String");
+	deepSetArg(session, connectionPath, "after", [], "$after");
+
 	if (spec.childRelationships) {
 		for (const child of spec.childRelationships) {
-			selectChildRelationship(session, schema, nodePath, child);
+			selectChildRelationship(session, schema, nodePath, child, extraWarnings);
 		}
 	}
 
 	const first = spec.first ?? 10;
 	deepSetArg(session, connectionPath, "first", [], String(first));
 
-	addVariable(session, "after", "String");
-	deepSetArg(session, connectionPath, "after", [], "$after");
-
 	selectLeaf(session, [...connectionPath, "pageInfo", "hasNextPage"]);
 	selectLeaf(session, [...connectionPath, "pageInfo", "endCursor"]);
 
 	if (spec.filter) {
-		promoteVariables(session, schema, connectionPath, "where", spec.filter);
+		promoteVariables(session, schema, connectionPath, "where", spec.filter, extraWarnings);
 		deepSetArg(session, connectionPath, "where", [], JSON.stringify(spec.filter));
 	}
 
 	const orderBy = normalizeOrderBy(spec.orderBy);
 	if (orderBy) {
-		promoteVariables(session, schema, connectionPath, "orderBy", orderBy);
+		promoteVariables(session, schema, connectionPath, "orderBy", orderBy, extraWarnings);
 		deepSetArg(session, connectionPath, "orderBy", [], JSON.stringify(orderBy));
 	}
 
 	if (spec.scope) {
-		promoteVariables(session, schema, connectionPath, "scope", spec.scope);
+		promoteVariables(session, schema, connectionPath, "scope", spec.scope, extraWarnings);
 		deepSetArg(session, connectionPath, "scope", [], spec.scope);
 	}
 
-	return buildOutput(session, schema, primingNote);
+	return buildOutput(session, schema, primingNote, extraWarnings);
 }

package/src/intent/select-child-relationship.ts

@@ -25,6 +25,7 @@ export function selectChildRelationship(
 	schema: GraphQLSchema,
 	parentNodePath: string[],
 	child: ChildRelationshipSpec,
+	warnings?: string[],
 ): void {
 	const childConnectionPath = [...parentNodePath, child.relationshipName];
 	const childNodePath = [...childConnectionPath, "edges", "node"];
@@ -37,12 +38,12 @@ export function selectChildRelationship(
 		deepSetArg(session, childConnectionPath, "first", [], String(child.first));
 	}
 	if (child.filter) {
-		promoteVariables(session, schema, childConnectionPath, "where", child.filter);
+		promoteVariables(session, schema, childConnectionPath, "where", child.filter, warnings);
 		deepSetArg(session, childConnectionPath, "where", [], JSON.stringify(child.filter));
 	}
 	const childOrderBy = normalizeOrderBy(child.orderBy);
 	if (childOrderBy) {
-		promoteVariables(session, schema, childConnectionPath, "orderBy", childOrderBy);
+		promoteVariables(session, schema, childConnectionPath, "orderBy", childOrderBy, warnings);
 		deepSetArg(session, childConnectionPath, "orderBy", [], JSON.stringify(childOrderBy));
 	}
 }

package/src/lib/__tests__/apply-command.spec.ts

@@ -17,10 +17,11 @@ const SCHEMA: GraphQLSchema = buildSchema(`
 	type RecordQuery {
 		Case(first: Int, after: String, where: Case_Filter, orderBy: Case_OrderBy): CaseConnection!
 	}
-	input Case_Filter { Status: PicklistOperators, Subject: StringOperators }
+	input Case_Filter { Status: PicklistOperators, Subject: StringOperators, Amount: DoubleOperators }
 	input Case_OrderBy { CreatedDate: OrderByClause }
 	input PicklistOperators { eq: String, ne: String, in: [String!] }
 	input StringOperators { eq: String, like: String }
+	input DoubleOperators { eq: Float, gt: Float }
 	input OrderByClause { order: Order! }
 	enum Order { ASC DESC }
 	type CaseConnection { edges: [CaseEdge!]!, pageInfo: PageInfo! }
@@ -95,6 +96,21 @@ describe("lib/apply-command — var", () => {
 		const session = createSession(ORG, "query", ORG_URL);
 		expect(() => applyCommand(session, SCHEMA, "var")).toThrow();
 	});
+
+	// W-22697670: re-declaring a $var with a conflicting type is rejected (first-wins
+	// keeps the original type; the define/var path surfaces the collision instead of
+	// silently misreporting the new type and producing an invalid query).
+	it("throws when a $var is re-declared with a conflicting type", () => {
+		const session = createSession(ORG, "query", ORG_URL);
+		applyCommand(session, SCHEMA, "var $x uiapi/query/Case/@args/where/Status/eq"); // String
+		expect(() =>
+			applyCommand(session, SCHEMA, "var $x uiapi/query/Case/@args/where/Amount/gt"),
+		).toThrow(/already declared as String; cannot redefine it as Float/);
+		// First-wins: $x stays String and is not bound at the Float position.
+		const q = renderQuery(session);
+		expect(q).toMatch(/\$x:\s*String/);
+		expect(q).not.toMatch(/\$x:\s*Float/);
+	});
 });
 
 describe("lib/apply-command — set", () => {

package/src/lib/__tests__/query-builder.spec.ts

@@ -4,6 +4,7 @@
  * For full license text, see the LICENSE.txt file
  */
 
+import { parse } from "graphql";
 import { describe, expect, it } from "vitest";
 import { makeSession, TEST_SCHEMA } from "../../__tests__/helpers/schema.js";
 import { selectLeafInSession } from "../../commands/query.js";
@@ -58,6 +59,73 @@ describe("query-builder", () => {
 		});
 	});
 
+	describe("bare-$ variable render guard", () => {
+		it("renders a valid placeholder as a bare variable reference", () => {
+			const session = makeSession();
+
+			addVariable(session, "$foo", "Int");
+
+			session.navigationPath = ["query", "accounts"];
+			setArg(session, ["accounts"], "first", "$foo");
+
+			session.navigationPath = ["query", "accounts", "edges", "node"];
+			selectLeaf(session, ["accounts", "edges", "node", "name"]);
+
+			const query = renderQuery(session);
+			// Bare reference: emitted as $foo, not quoted "$foo".
+			expect(query).toMatch(/first: \$foo\b/);
+			expect(query).not.toContain('"$foo"');
+		});
+
+		it("renders an invalid placeholder ($1var) as a quoted literal", () => {
+			const session = makeSession();
+
+			session.navigationPath = ["query", "accounts"];
+			setArg(session, ["accounts"], "first", "$1var");
+
+			session.navigationPath = ["query", "accounts", "edges", "node"];
+			selectLeaf(session, ["accounts", "edges", "node", "name"]);
+
+			const query = renderQuery(session);
+			// $1var is not a valid GraphQL Name -> quoted literal, not a bare var.
+			expect(query).toContain('first: "$1var"');
+			expect(query).not.toMatch(/first: \$1var\b/);
+		});
+
+		it("renders a hyphenated placeholder ($foo-bar) as a quoted literal", () => {
+			const session = makeSession();
+
+			session.navigationPath = ["query", "accounts"];
+			setArg(session, ["accounts"], "first", "$foo-bar");
+
+			session.navigationPath = ["query", "accounts", "edges", "node"];
+			selectLeaf(session, ["accounts", "edges", "node", "name"]);
+
+			const query = renderQuery(session);
+			// $foo-bar is not a valid GraphQL Name -> quoted literal, not a bare var.
+			expect(query).toContain('first: "$foo-bar"');
+			expect(query).not.toMatch(/first: \$foo-bar\b/);
+		});
+
+		// W-22697670 (PR #654 review): control chars in a string value are escaped via
+		// JSON.stringify, so the rendered literal is well-formed and graphql.parse()
+		// accepts it — a raw newline previously produced an "Unterminated string" error.
+		it("escapes control chars in a string literal so the query stays parseable", () => {
+			const session = makeSession();
+
+			session.navigationPath = ["query", "accounts"];
+			setArg(session, ["accounts"], "first", "a\nb\tc");
+
+			session.navigationPath = ["query", "accounts", "edges", "node"];
+			selectLeaf(session, ["accounts", "edges", "node", "name"]);
+
+			const query = renderQuery(session);
+			expect(query).toContain("first: " + JSON.stringify("a\nb\tc"));
+			expect(query).not.toContain("a\nb"); // no raw newline inside the literal
+			expect(() => parse(query)).not.toThrow();
+		});
+	});
+
 	describe("aliasing rendering", () => {
 		it("renders multiple aliased instances with different variables", () => {
 			const session = makeSession();

package/src/lib/__tests__/session.spec.ts

@@ -7,6 +7,7 @@
 import { describe, expect, it } from "vitest";
 import { makeSession } from "../../__tests__/helpers/schema.js";
 import { renderQuery } from "../query-builder.js";
+import type { VariableTypeCollision } from "../session.js";
 import {
 	addVariable,
 	appendListElement,
@@ -270,6 +271,49 @@ describe("session", () => {
 		});
 	});
 
+	describe("addVariable type-collision (W-22697670)", () => {
+		it("returns undefined and records the entry for a new variable name", () => {
+			const session = makeSession();
+
+			const collision = addVariable(session, "$limit", "Int");
+
+			expect(collision).toBeUndefined();
+			expect(session.variables).toHaveLength(1);
+			expect(session.variables[0]).toMatchObject({ name: "limit", type: "Int" });
+		});
+
+		it("returns undefined when the same name is re-declared with the SAME type", () => {
+			const session = makeSession();
+
+			const first = addVariable(session, "$status", "String");
+			const second = addVariable(session, "$status", "String");
+
+			expect(first).toBeUndefined();
+			expect(second).toBeUndefined();
+			expect(session.variables).toHaveLength(1);
+			expect(session.variables[0]).toMatchObject({ name: "status", type: "String" });
+		});
+
+		it("keeps the first-declared type and reports a collision on a DIFFERENT type (first-wins)", () => {
+			const session = makeSession();
+
+			const first = addVariable(session, "$amount", "String");
+			const second = addVariable(session, "$amount", "Float");
+
+			expect(first).toBeUndefined();
+			const collision: VariableTypeCollision | undefined = second;
+			expect(collision).toEqual({
+				name: "amount",
+				existingType: "String",
+				ignoredType: "Float",
+			});
+
+			// First-wins: the stored variable still has the FIRST type, not the conflicting one.
+			expect(session.variables).toHaveLength(1);
+			expect(session.variables[0]).toMatchObject({ name: "amount", type: "String" });
+		});
+	});
+
 	describe("runtime variable building", () => {
 		it("runtime variables are built from runtime values and defaults", () => {
 			const session = makeSession();

package/src/lib/__tests__/variable-promotion.spec.ts

@@ -170,6 +170,64 @@ describe("variable-promotion", () => {
 			expect(session.variables).toHaveLength(0);
 		});
 
+		it("warns on a type collision and keeps the first inferred type (first-wins)", () => {
+			const session = makeSession();
+			const warnings: string[] = [];
+
+			// The same $dup reference appears at two leaves with DIFFERENT inferred
+			// types: Status.eq is `Picklist` (PicklistOperators.eq) and Industry.eq
+			// is `String` (StringOperators.eq). The walker processes keys in
+			// insertion order, so Status is seen first and wins; the later String
+			// inference is reported as a collision and ignored.
+			promoteVariables(
+				session,
+				schema,
+				accountFieldPath,
+				"where",
+				{
+					Status: { eq: "$dup" },
+					Industry: { eq: "$dup" },
+				},
+				warnings,
+			);
+
+			// First-wins: only one variable, keeping the first (Picklist) type.
+			expect(session.variables).toHaveLength(1);
+			expect(session.variables[0]!.name).toBe("dup");
+			expect(session.variables[0]!.type).toBe("Picklist");
+
+			// A collision warning naming the variable was surfaced to the sink.
+			const collisionWarning = warnings.find((w) => w.includes("type collision for $"));
+			expect(collisionWarning).toBeDefined();
+			expect(collisionWarning).toContain("type collision for $dup");
+			// The warning explains which type was kept and which was ignored.
+			expect(collisionWarning).toContain("Picklist");
+			expect(collisionWarning).toContain("String");
+		});
+
+		it("does not warn when the same $var is reused with the same inferred type", () => {
+			const session = makeSession();
+			const warnings: string[] = [];
+
+			// Both leaves are `String` (StringOperators.eq / .like), so reusing $dup
+			// is consistent — no collision, no warning, one variable.
+			promoteVariables(
+				session,
+				schema,
+				accountFieldPath,
+				"where",
+				{
+					Industry: { eq: "$dup", like: "$dup" },
+				},
+				warnings,
+			);
+
+			expect(session.variables).toHaveLength(1);
+			expect(session.variables[0]!.name).toBe("dup");
+			expect(session.variables[0]!.type).toBe("String");
+			expect(warnings.some((w) => w.includes("type collision"))).toBe(false);
+		});
+
 		it("strips a trailing ! when the inferred type is non-null", () => {
 			// The schema has Account_Filter.Or: [Account_OrderBy!] — the nested
 			// element is non-null. If a $var is placed where a non-null is required,

package/src/lib/auth.ts

@@ -7,6 +7,7 @@
 import fs from "fs";
 import path from "path";
 import { Org, AuthInfo } from "@salesforce/core";
+import { AuthError } from "./errors.js";
 import { graphitiHome } from "./fs-utils.js";
 
 export interface OrgAuth {
@@ -70,14 +71,15 @@ export async function getOrgAuth(orgAlias: string): Promise<OrgAuth> {
 		connection = org.getConnection();
 	} catch (err) {
 		const msg = err instanceof Error ? err.message : String(err);
-		throw new Error(
+		throw new AuthError(
 			`Failed to get org info for "${orgAlias}". Is the alias correct? Have you run \`sf org login web --alias ${orgAlias}\`?\n${msg}`,
+			{ cause: err },
 		);
 	}
 
 	const fields = connection.getAuthInfo().getFields();
 	if (!connection.accessToken || !connection.instanceUrl) {
-		throw new Error(
+		throw new AuthError(
 			`Missing accessToken or instanceUrl for "${orgAlias}". Token may have expired -- try \`sf org login web --alias ${orgAlias}\` to re-authenticate.`,
 		);
 	}

package/src/lib/errors.ts

@@ -0,0 +1,45 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+/**
+ * Typed error markers used to classify failures at the MCP tool boundary
+ * (W-22697673). The MCP adapter (`schemas/tool-adapter.ts`) maps these
+ * to category prefixes — `Auth:` / `Schema:` / `UserInput:` — so an agent can
+ * distinguish an infra/auth/schema failure from a user-input mistake without
+ * parsing free text. `MutationContextError` (walker) is also treated as
+ * UserInput; message heuristics remain a secondary fallback for untyped throws.
+ * Everything unmatched falls through to `Internal:`.
+ */
+
+/** Credential/auth resolution failure (e.g. unknown org, expired token). → `Auth:` */
+export class AuthError extends Error {
+	constructor(message: string, opts?: { cause?: unknown }) {
+		super(message, opts?.cause !== undefined ? { cause: opts.cause } : undefined);
+		this.name = "AuthError";
+	}
+}
+
+/**
+ * Agent-supplied input or spec violation that the user can fix: an unknown
+ * type/field/argument named in a request, an invalid navigation, a malformed
+ * command. → `UserInput:`. Carrying this typed marker keeps classification off
+ * the brittle message-shape heuristics for the navigation/validation sites that
+ * throw it.
+ */
+export class UserInputError extends Error {
+	constructor(message: string, opts?: { cause?: unknown }) {
+		super(message, opts?.cause !== undefined ? { cause: opts.cause } : undefined);
+		this.name = "UserInputError";
+	}
+}
+
+/** Schema introspection / priming / build failure. → `Schema:` */
+export class SchemaError extends Error {
+	constructor(message: string, opts?: { cause?: unknown }) {
+		super(message, opts?.cause !== undefined ? { cause: opts.cause } : undefined);
+		this.name = "SchemaError";
+	}
+}

package/src/lib/introspect.ts

@@ -10,6 +10,7 @@ import fs from "fs";
 import path from "path";
 import { Org, type Connection } from "@salesforce/core";
 import type { OrgAuth } from "./auth.js";
+import { SchemaError } from "./errors.js";
 import { atomicWriteJson, graphitiHome } from "./fs-utils.js";
 
 // Re-export for backward compatibility with existing graphiti consumers.
@@ -277,12 +278,12 @@ export async function downloadSchema(auth: OrgAuth): Promise<SchemaMetadata> {
 		const messages = (rawResult.errors as any[])
 			.map((e: any) => e.message ?? JSON.stringify(e))
 			.join("\n  ");
-		throw new Error(`Introspection query returned errors:\n  ${messages}`);
+		throw new SchemaError(`Introspection query returned errors:\n  ${messages}`);
 	}
 
 	const rawSchema = rawResult?.data?.__schema ?? rawResult?.__schema;
 	if (!rawSchema) {
-		throw new Error("Introspection query did not return a __schema field");
+		throw new SchemaError("Introspection query did not return a __schema field");
 	}
 
 	const { result, removedCount } = stripDataCloudTypes(rawResult);
@@ -317,7 +318,9 @@ export async function downloadSchema(auth: OrgAuth): Promise<SchemaMetadata> {
 export function loadIntrospectionResult(instanceUrl: string): any {
 	const fp = schemaPathForInstanceUrl(normalizeInstanceUrl(instanceUrl));
 	if (!fs.existsSync(fp)) {
-		throw new Error(`No cached schema for "${instanceUrl}". Run \`graphiti connect <org>\` first.`);
+		throw new SchemaError(
+			`No cached schema for "${instanceUrl}". Run \`graphiti connect <org>\` first.`,
+		);
 	}
 	return JSON.parse(fs.readFileSync(fp, "utf-8"));
 }

package/src/lib/prime-schema.ts

@@ -7,6 +7,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { getOrgAuth as realGetOrgAuth, type OrgAuth } from "./auth.js";
+import { SchemaError } from "./errors.js";
 import {
 	downloadSchema as realDownloadSchema,
 	getSchemaMetadata,
@@ -95,7 +96,7 @@ export async function withSchemaLock<T>(
 			}
 
 			if (Date.now() - startedWaitingAt > MAX_WAIT_MS) {
-				throw new Error(
+				throw new SchemaError(
 					`Timed out waiting ${MAX_WAIT_MS}ms for schema priming lock at ${lockPath}`,
 				);
 			}
@@ -281,9 +282,16 @@ export async function primeSchemaWithLock(
 				// through.
 				meta = await deps.downloadSchema(auth);
 			} catch (cause) {
-				// Lazy prime (no existing cache): surface the raw error verbatim
-				// (FR-13.5/13.6) — there is no stale cache to keep.
-				if (!forceRefresh) throw cause;
+				// Lazy prime (no existing cache): no stale cache to keep, so surface
+				// the underlying failure (FR-13.5/13.6). Wrap untyped causes (e.g. a
+				// raw @salesforce/core/jsforce network error from connection.request)
+				// in SchemaError so the MCP boundary classifies priming failures as
+				// `Schema:`; a cause that is already SchemaError passes through.
+				if (!forceRefresh) {
+					if (cause instanceof SchemaError) throw cause;
+					const msg = cause instanceof Error ? cause.message : String(cause);
+					throw new SchemaError(`Schema priming failed for "${orgAlias}": ${msg}`, { cause });
+				}
 				// Forced refresh: atomic writes mean the old JSON is still on
 				// disk, so surface a staleness-aware error and leave every cache
 				// untouched.

package/src/lib/query-builder.ts

@@ -4,6 +4,7 @@
  * For full license text, see the LICENSE.txt file
  */
 
+import { GRAPHQL_NAME_RE } from "./graphql-name.js";
 import type { QuerySession, ProjectionNode, DirectiveNode } from "./session.js";
 import { getChildren, getEffectiveArgs } from "./session.js";
 
@@ -133,8 +134,10 @@ function renderDirective(dir: DirectiveNode): string {
 function formatArgValue(value: string): string {
 	const trimmed = value.trim();
 
-	// Variable reference
-	if (trimmed.startsWith("$")) return trimmed;
+	// Variable reference — only when the name is a valid GraphQL Name. A typo'd
+	// $-string (e.g. "$1var", "$foo-bar") falls through and is quoted as a literal
+	// rather than emitted as an undeclared bare variable reference.
+	if (trimmed.startsWith("$") && GRAPHQL_NAME_RE.test(trimmed.slice(1))) return trimmed;
 
 	// Numeric
 	if (/^-?\d+(\.\d+)?$/.test(trimmed)) return trimmed;
@@ -153,8 +156,12 @@ function formatArgValue(value: string): string {
 	// Quoted string — pass through
 	if (trimmed.startsWith('"') && trimmed.endsWith('"')) return trimmed;
 
-	// Default: wrap in quotes
-	return `"${trimmed.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+	// Default: a string literal. JSON.stringify produces a spec-valid GraphQL string
+	// literal — it escapes line terminators and control chars (\n \r \t \b \f) and
+	// quotes/backslashes — so values like "a\nb" don't render a raw newline that
+	// graphql.parse() would reject as an unterminated string. (U+2028/U+2029 pass
+	// through raw and are handled at the MCP text boundary, not here.)
+	return JSON.stringify(trimmed);
 }
 
 /**
@@ -176,10 +183,16 @@ function valueToGraphQL(value: unknown): string {
 	if (typeof value === "boolean") return String(value);
 	if (typeof value === "number") return String(value);
 	if (typeof value === "string") {
-		if (value.startsWith("$")) return value;
+		// Bare variable reference only when the name is a valid GraphQL Name;
+		// otherwise quote it as a literal (a typo'd $-string is not a declared var).
+		if (value.startsWith("$") && GRAPHQL_NAME_RE.test(value.slice(1))) return value;
 		// Emit uppercase identifiers as bare enum tokens (e.g. DESC, ASC, EVERYTHING)
 		if (/^[A-Z_][A-Z0-9_]*$/.test(value)) return value;
-		return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+		// JSON.stringify yields a spec-valid GraphQL string literal that escapes line
+		// terminators and control chars (\n \r \t \b \f), unlike a manual \ / " escape
+		// which would leave a raw newline that graphql.parse() rejects. (U+2028/U+2029
+		// pass through raw and are handled at the MCP text boundary, not here.)
+		return JSON.stringify(value);
 	}
 	if (Array.isArray(value)) {
 		return `[${value.map(valueToGraphQL).join(", ")}]`;

package/src/lib/session.ts

@@ -995,20 +995,37 @@ export function removeNodeByIdWithPrune(session: QuerySession, nodeId: string):
 	return true;
 }
 
+/**
+ * A type-conflicting `$var` redeclaration detected by {@link addVariable}.
+ * The first-declared type is kept (first-wins); the later inference is ignored.
+ */
+export interface VariableTypeCollision {
+	name: string;
+	existingType: string;
+	ignoredType: string;
+}
+
 export function addVariable(
 	session: QuerySession,
 	name: string,
 	type: string,
 	defaultValue?: string,
-): void {
+): VariableTypeCollision | undefined {
 	const cleanName = normalizeVariableName(name);
 	const existing = session.variables.find((variable) => variable.name === cleanName);
 	if (existing) {
-		existing.type = type;
+		// First-wins: a variable referenced more than once (e.g. across two filter
+		// leaves) keeps its first-declared type. Last-wins would silently overwrite
+		// it and render a query UIAPI rejects at runtime. Report the conflict so a
+		// caller with a warnings sink can surface it.
+		if (existing.type !== type) {
+			return { name: cleanName, existingType: existing.type, ignoredType: type };
+		}
 		existing.defaultValue = defaultValue;
-		return;
+		return undefined;
 	}
 	session.variables.push({ name: cleanName, type, defaultValue });
+	return undefined;
 }
 
 export function setVariableRuntimeValue(

package/src/lib/variable-promotion.ts

@@ -93,15 +93,21 @@ function walk(
 			return;
 		}
 		const varName = m[1];
+		let declared: string;
 		try {
 			const { inferredType } = inferTypeFromArgsPath(schema, session.operation, fieldSchemaPath, [
 				argName,
 				...pathInsideArg,
 			]);
-			const declared = inferredType.endsWith("!") ? inferredType.slice(0, -1) : inferredType;
-			addVariable(session, varName, declared);
+			declared = inferredType.endsWith("!") ? inferredType.slice(0, -1) : inferredType;
 		} catch {
-			addVariable(session, varName, "String");
+			declared = "String";
+		}
+		const collision = addVariable(session, varName, declared);
+		if (collision && warnings) {
+			warnings.push(
+				`Variable: type collision for $${collision.name} — first declaration as '${collision.existingType}' kept, later inference '${collision.ignoredType}' ignored. UIAPI requires one type per variable; reference $${collision.name} consistently or use distinct variable names.`,
+			);
 		}
 		return;
 	}