@salesforce/graphiti 10.10.2

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

@@ -0,0 +1,135 @@
+/**
+ * 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 { buildCreate } from "../build-create.js";
+
+const SCHEMA_SDL = `
+	type Query { _placeholder: Boolean }
+	type Mutation { uiapi(input: UIAPIMutationsInput): UIAPIMutations! }
+	input UIAPIMutationsInput { allOrNone: Boolean }
+	type UIAPIMutations {
+		AccountCreate(input: AccountCreateInput!): AccountCreatePayload
+		Custom_Object__cCreate(input: Custom_Object__cCreateInput!): Custom_Object__cCreatePayload
+	}
+	input AccountCreateInput { Account: AccountCreateRepresentation! }
+	input AccountCreateRepresentation { Name: String, Industry: String }
+	type AccountCreatePayload { Record: Account }
+	input Custom_Object__cCreateInput { Custom_Object__c: Custom_Object__cCreateRepresentation! }
+	input Custom_Object__cCreateRepresentation { Name: String }
+	type Custom_Object__cCreatePayload { 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-create-validation";
+const ORG_URL = "https://test-create-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-create — GraphQL name validation", () => {
+	describe("object name validation", () => {
+		it("throws for object with special characters: 'not valid!'", async () => {
+			await expect(
+				buildCreate({ 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(buildCreate({ 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(buildCreate({ 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 buildCreate(
+				{ org: ORG, object: "Custom_Object__c", returnFields: ["Id"] },
+				noopPrimeDeps(),
+			);
+			expect(result.query).toContain("Custom_Object__cCreate");
+		});
+
+		it("accepts standard object name: 'Account'", async () => {
+			const result = await buildCreate(
+				{ org: ORG, object: "Account", returnFields: ["Id"] },
+				noopPrimeDeps(),
+			);
+			expect(result.query).toContain("mutation CreateAccount");
+		});
+
+		it("accepts object starting with underscore: '_Foo'", async () => {
+			// The regex allows underscore as first char per GraphQL spec
+			await expect(
+				buildCreate({ org: ORG, object: "_Foo" }, noopPrimeDeps()),
+			).resolves.toBeDefined();
+		});
+	});
+
+	describe("inputVariable name validation", () => {
+		it("throws for inputVariable with spaces: 'has spaces'", async () => {
+			await expect(
+				buildCreate({ 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(
+				buildCreate({ 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(
+				buildCreate({ 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 buildCreate(
+				{ org: ORG, object: "Account", inputVariable: "$myInput" },
+				noopPrimeDeps(),
+			);
+			// The leading $ is stripped by existing code before validation
+			expect(result.query).toContain("$myInput");
+		});
+
+		it("accepts valid inputVariable: 'accountInput'", async () => {
+			const result = await buildCreate(
+				{ org: ORG, object: "Account", inputVariable: "accountInput" },
+				noopPrimeDeps(),
+			);
+			expect(result.query).toContain("$accountInput");
+		});
+
+		it("accepts default inputVariable 'input' when not specified", async () => {
+			const result = await buildCreate({ 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(
+				buildCreate({ org: ORG, object: "Account", operationName: "has spaces" }, noopPrimeDeps()),
+			).rejects.toThrow(/buildMutation: operationName 'has spaces' is not a valid GraphQL Name/);
+		});
+	});
+});

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

@@ -0,0 +1,121 @@
+/**
+ * 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 { buildDelete } from "../build-delete.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 {
+		AccountDelete(input: RecordDeleteInput!): RecordDeletePayload
+		Custom_Object__cDelete(input: RecordDeleteInput!): RecordDeletePayload
+	}
+	input RecordDeleteInput { Id: ID! }
+	type RecordDeletePayload { Id: ID }
+	type Account { Id: ID!, Name: StringValue }
+	type Custom_Object__c { Id: ID!, Name: StringValue }
+	type StringValue { value: String }
+`;
+
+const ORG = "test-delete";
+const ORG_URL = "https://test-delete.my.salesforce.com";
+const SCHEMA = buildSchema(SCHEMA_SDL);
+primeSchemaCache(ORG, SCHEMA);
+primeSchemaCache(ORG_URL, SCHEMA);
+
+function noopPrimeDeps() {
+	return makeNoopPrimeDeps(ORG, ORG_URL, SCHEMA);
+}
+
+describe("intent/build-delete", () => {
+	it("renders a delete mutation with RecordDeleteInput! and selects Id only", async () => {
+		const result = await buildDelete({ org: ORG, object: "Account" }, noopPrimeDeps());
+
+		expect(result.query).toContain("mutation DeleteAccount");
+		expect(result.query).toContain("$input: RecordDeleteInput!");
+		expect(result.query).toContain("AccountDelete(input: $input)");
+		// Id is plain ID on the payload — selected directly, never `Id { value }`.
+		expect(result.query).toMatch(/AccountDelete\(input: \$input\)\s*{\s*Id\s*}/);
+		// No `Record { ... }` sub-selection (delete payloads have no Record path).
+		expect(result.query).not.toMatch(/\bRecord\s*{/);
+		expect(result.query).not.toContain("Id { value }");
+	});
+
+	it("declares a single required input variable of type RecordDeleteInput!", async () => {
+		const result = await buildDelete({ org: ORG, object: "Account" }, noopPrimeDeps());
+
+		expect(result.variables).toEqual([
+			{ name: "input", type: "RecordDeleteInput!", required: true },
+		]);
+	});
+
+	it("uses RecordDeleteInput! for custom objects too (schema-wide, not <Object>-specific)", async () => {
+		const result = await buildDelete({ org: ORG, object: "Custom_Object__c" }, noopPrimeDeps());
+
+		expect(result.query).toContain("Custom_Object__cDelete(input: $input)");
+		expect(result.query).toContain("$input: RecordDeleteInput!");
+		// Crucially NOT Custom_Object__cDeleteInput.
+		expect(result.query).not.toContain("Custom_Object__cDeleteInput");
+	});
+
+	it("honors a custom operationName", async () => {
+		const result = await buildDelete(
+			{ org: ORG, object: "Account", operationName: "RemoveAcct" },
+			noopPrimeDeps(),
+		);
+		expect(result.query).toContain("mutation RemoveAcct");
+	});
+
+	it("honors a custom inputVariable and strips a leading $", async () => {
+		const result = await buildDelete(
+			{ org: ORG, object: "Account", inputVariable: "$acctInput" },
+			noopPrimeDeps(),
+		);
+		expect(result.query).toContain("$acctInput: RecordDeleteInput!");
+		expect(result.query).toContain("AccountDelete(input: $acctInput)");
+	});
+
+	it("produces no validation warnings for a well-formed delete", async () => {
+		const result = await buildDelete({ org: ORG, object: "Account" }, noopPrimeDeps());
+		expect(result.warnings.filter((w) => w.startsWith("Validation:"))).toEqual([]);
+	});
+
+	it("throws for an object that is not a valid GraphQL Name", async () => {
+		await expect(buildDelete({ org: ORG, object: "my-object" }, noopPrimeDeps())).rejects.toThrow(
+			/buildDelete: object 'my-object' is not a valid GraphQL Name/,
+		);
+	});
+
+	it("throws for an inputVariable that is not a valid GraphQL Name", async () => {
+		await expect(
+			buildDelete({ org: ORG, object: "Account", inputVariable: "has spaces" }, noopPrimeDeps()),
+		).rejects.toThrow(/buildDelete: inputVariable 'has spaces' is not a valid GraphQL Name/);
+	});
+
+	it("throws for an operationName that is not a valid GraphQL Name", async () => {
+		await expect(
+			buildDelete({ org: ORG, object: "Account", operationName: "has spaces" }, noopPrimeDeps()),
+		).rejects.toThrow(/buildDelete: operationName '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 buildDelete({ org: ORG, object: "Account" }, noopPrimeDeps());
+		expect(spy).toHaveBeenCalledWith(ORG, "mutation", ORG_URL);
+	});
+});

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

@@ -0,0 +1,333 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import path from "node:path";
+import { buildSchema, introspectionFromSchema } from "graphql";
+import { describe, expect, it, vi } from "vitest";
+import { atomicWriteJson } from "../../lib/fs-utils.js";
+import {
+	schemaCacheKeyForInstanceUrl,
+	schemaDir,
+	type SchemaMetadata,
+} from "../../lib/introspect.js";
+import { type PrimeDeps } from "../../lib/prime-schema.js";
+import * as sessionModule from "../../lib/session.js";
+import { primeSchemaCache } from "../../lib/walker.js";
+import { buildDetail } from "../build-detail.js";
+
+vi.mock("../../lib/session.js", async (importOriginal) => {
+	const actual = await importOriginal<typeof sessionModule>();
+	return { ...actual, createSession: vi.fn(actual.createSession) };
+});
+
+// SDL mirrors build-list.spec.ts but extends every `_Filter` with an
+// `Id: IDOperators` field so the FR-5.5 `where: { Id: { eq: $id } }` binding
+// validates cleanly. Without it, the rendered query would still be correct
+// but graphql-js validate() would warn — that's fine in production (real
+// UIAPI filters all expose Id), and we don't want spurious warnings noise
+// in test assertions.
+const SCHEMA_SDL = `
+	type Query { uiapi: UIAPI! }
+	type UIAPI { query: RecordQuery! }
+
+	type RecordQuery {
+		Account(first: Int, after: String, where: Account_Filter, orderBy: Account_OrderBy, scope: Scope): AccountConnection!
+		Case(first: Int, after: String, where: Case_Filter, orderBy: Case_OrderBy, scope: Scope): CaseConnection!
+	}
+
+	enum Scope { MINE EVERYTHING }
+	enum Order { ASC DESC }
+
+	input Account_Filter { Id: IDOperators, Industry: PicklistOperators, Name: StringOperators }
+	input Account_OrderBy { Name: OrderByClause, Industry: OrderByClause }
+	input Case_Filter { Id: IDOperators, Status: PicklistOperators, Priority: PicklistOperators }
+	input Case_OrderBy { CreatedDate: OrderByClause }
+	input IDOperators { eq: ID, ne: ID, in: [ID!] }
+	input PicklistOperators { eq: String, ne: String, in: [String!] }
+	input StringOperators { eq: String, like: String }
+	input OrderByClause { order: Order!, nulls: NullsOrder }
+	enum NullsOrder { FIRST LAST }
+
+	type AccountConnection {
+		edges: [AccountEdge!]!
+		pageInfo: PageInfo!
+		totalCount: Int
+	}
+	type AccountEdge { node: Account! }
+	type CaseConnection {
+		edges: [CaseEdge!]!
+		pageInfo: PageInfo!
+	}
+	type CaseEdge { node: Case! }
+	type PageInfo { hasNextPage: Boolean!, endCursor: String }
+
+	type Account {
+		Id: ID!
+		Name: StringValue
+		Industry: StringValue
+		Owner: OwnerUnion
+		Contacts(first: Int, where: Contact_Filter, orderBy: Contact_OrderBy): ContactConnection
+	}
+	type Case {
+		Id: ID!
+		Subject: StringValue
+		Status: StringValue
+		Owner: OwnerUnion
+		Account: Account
+	}
+
+	type ContactConnection { edges: [ContactEdge!]! }
+	type ContactEdge { node: Contact! }
+	input Contact_Filter { Id: IDOperators, Title: StringOperators }
+	input Contact_OrderBy { LastName: OrderByClause }
+
+	type Contact {
+		Id: ID!
+		LastName: StringValue
+		Title: StringValue
+	}
+
+	union OwnerUnion = User | Group
+	type User { Id: ID!, Name: StringValue, Email: StringValue }
+	type Group { Id: ID!, Name: StringValue }
+
+	type StringValue { value: String }
+`;
+
+const ORG = "test-detail";
+const ORG_URL = "https://test-detail.my.salesforce.com";
+const SCHEMA = buildSchema(SCHEMA_SDL);
+primeSchemaCache(ORG, SCHEMA);
+primeSchemaCache(ORG_URL, SCHEMA);
+
+function noopPrimeDeps(): PrimeDeps {
+	return {
+		getOrgAuth: async () => ({
+			alias: ORG,
+			username: "u",
+			instanceUrl: ORG_URL,
+			accessToken: "t",
+			orgId: "00D",
+		}),
+		downloadSchema: async (auth) => {
+			const cacheKey = schemaCacheKeyForInstanceUrl(auth.instanceUrl);
+			const filePath = path.join(schemaDir(), `${cacheKey}.json`);
+			atomicWriteJson(filePath, { data: introspectionFromSchema(SCHEMA) });
+			const meta: SchemaMetadata = {
+				cacheKey,
+				instanceUrl: auth.instanceUrl,
+				typeCount: 0,
+				downloadedAt: new Date().toISOString(),
+				filePath,
+			};
+			return meta;
+		},
+	};
+}
+
+describe("intent/build-detail", () => {
+	it("declares $id: ID! and binds where { Id: { eq: $id } } with first: 1 (FR-5.5)", async () => {
+		const out = await buildDetail(
+			{ org: ORG, object: "Account", fields: ["Id", "Name"] },
+			noopPrimeDeps(),
+		);
+		const id = out.variables.find((v) => v.name === "id");
+		expect(id).toBeDefined();
+		expect(id!.type).toBe("ID!");
+		expect(id!.required).toBe(true);
+		expect(out.query).toMatch(/\$id\s*:\s*ID!/);
+		expect(out.query).toMatch(/where\s*:\s*\{\s*Id\s*:\s*\{\s*eq\s*:\s*\$id\s*\}/);
+		expect(out.query).toMatch(/first\s*:\s*1\b/);
+	});
+
+	it("respects custom idVariable name", async () => {
+		const out = await buildDetail(
+			{ org: ORG, object: "Account", fields: ["Id"], idVariable: "accountId" },
+			noopPrimeDeps(),
+		);
+		const accountId = out.variables.find((v) => v.name === "accountId");
+		expect(accountId).toBeDefined();
+		expect(accountId!.type).toBe("ID!");
+		expect(out.query).toMatch(/\$accountId\s*:\s*ID!/);
+		expect(out.query).toMatch(/where\s*:\s*\{\s*Id\s*:\s*\{\s*eq\s*:\s*\$accountId\s*\}/);
+		// And no leftover `$id` from the default.
+		expect(out.variables.find((v) => v.name === "id")).toBeUndefined();
+	});
+
+	it("scalar fields select { value } except Id (FR-4.1)", async () => {
+		const out = await buildDetail(
+			{ org: ORG, object: "Account", fields: ["Id", "Name"] },
+			noopPrimeDeps(),
+		);
+		expect(out.query).toMatch(/\bId\b/);
+		expect(out.query).toMatch(/Name\s*\{\s*value\s*\}/);
+	});
+
+	it("default operationName is <Object>Detail", async () => {
+		const out = await buildDetail({ org: ORG, object: "Case", fields: ["Id"] }, noopPrimeDeps());
+		expect(out.query).toMatch(/\bquery\s+CaseDetail\b/);
+	});
+
+	it("respects custom operationName", async () => {
+		const out = await buildDetail(
+			{ org: ORG, object: "Case", fields: ["Id"], operationName: "GetMyCase" },
+			noopPrimeDeps(),
+		);
+		expect(out.query).toMatch(/\bquery\s+GetMyCase\b/);
+	});
+
+	it("rejects an operationName that is not a valid GraphQL Name", async () => {
+		await expect(
+			buildDetail(
+				{ org: ORG, object: "Account", fields: ["Id"], operationName: "has spaces" },
+				noopPrimeDeps(),
+			),
+		).rejects.toThrow(/buildDetail: operationName 'has spaces' is not a valid GraphQL Name/);
+	});
+
+	it("rejects an object that is not a valid GraphQL Name", async () => {
+		await expect(
+			buildDetail({ org: ORG, object: "Order Item", fields: ["Id"] }, noopPrimeDeps()),
+		).rejects.toThrow(/buildDetail: object 'Order Item' is not a valid GraphQL Name/);
+	});
+
+	it("parentFields walks dotted path with value wrapping (FR-4.2)", async () => {
+		const out = await buildDetail(
+			{ org: ORG, object: "Case", fields: ["Id"], parentFields: ["Account.Name"] },
+			noopPrimeDeps(),
+		);
+		expect(out.query).toMatch(/Account\s*\{[^}]*Name\s*\{\s*value\s*\}/s);
+	});
+
+	it("parentFields expands polymorphic union into inline fragments (FR-4.3)", async () => {
+		const out = await buildDetail(
+			{ org: ORG, object: "Case", fields: ["Id"], parentFields: ["Owner.Name"] },
+			noopPrimeDeps(),
+		);
+		expect(out.query).toMatch(/\.\.\.\s+on\s+User\s*\{[^}]*Name\s*\{\s*value\s*\}/s);
+		expect(out.query).toMatch(/\.\.\.\s+on\s+Group\s*\{[^}]*Name\s*\{\s*value\s*\}/s);
+	});
+
+	it("parentFields skips union members lacking the field (FR-4.3)", async () => {
+		const out = await buildDetail(
+			{ org: ORG, object: "Case", fields: ["Id"], parentFields: ["Owner.Email"] },
+			noopPrimeDeps(),
+		);
+		expect(out.query).toMatch(/\.\.\.\s+on\s+User\s*\{[^}]*Email/s);
+		expect(out.query).not.toMatch(/\.\.\.\s+on\s+Group\s*\{[^}]*Email/s);
+	});
+
+	it("childRelationships rendered as edges/node connection with first/orderBy (FR-4.4)", async () => {
+		const out = await buildDetail(
+			{
+				org: ORG,
+				object: "Account",
+				fields: ["Id"],
+				childRelationships: [
+					{
+						relationshipName: "Contacts",
+						fields: ["Id", "LastName"],
+						first: 5,
+						orderBy: { LastName: { order: "ASC" } },
+					},
+				],
+			},
+			noopPrimeDeps(),
+		);
+		expect(out.query).toMatch(/Contacts\s*\([^)]*first:\s*5/);
+		expect(out.query).toMatch(/Contacts\s*\([^)]*orderBy:\s*\{\s*LastName/s);
+		expect(out.query).toMatch(
+			/Contacts\s*\([^)]*\)\s*\{\s*edges\s*\{\s*node\s*\{[^}]*LastName\s*\{\s*value\s*\}/s,
+		);
+	});
+
+	it("childRelationships filter $varName promotes typed variable (FR-5.1, 5.2)", async () => {
+		const out = await buildDetail(
+			{
+				org: ORG,
+				object: "Account",
+				fields: ["Id"],
+				childRelationships: [
+					{
+						relationshipName: "Contacts",
+						fields: ["Id"],
+						filter: { Title: { like: "$titlePattern" } },
+					},
+				],
+			},
+			noopPrimeDeps(),
+		);
+		const titlePattern = out.variables.find((v) => v.name === "titlePattern");
+		expect(titlePattern).toBeDefined();
+		expect(titlePattern!.required).toBe(false);
+		// Both the ID! and the promoted nullable variable coexist.
+		expect(out.variables.find((v) => v.name === "id")?.required).toBe(true);
+	});
+
+	it("does NOT declare $after or select pageInfo (negative vs sf_gql_list)", async () => {
+		const out = await buildDetail({ org: ORG, object: "Account", fields: ["Id"] }, noopPrimeDeps());
+		expect(out.variables.find((v) => v.name === "after")).toBeUndefined();
+		expect(out.query).not.toMatch(/\$after\b/);
+		expect(out.query).not.toMatch(/pageInfo\b/);
+	});
+
+	it("rendered query passes graphql-js validation (no Validation: warnings)", async () => {
+		const out = await buildDetail(
+			{ org: ORG, object: "Account", fields: ["Id", "Name"] },
+			noopPrimeDeps(),
+		);
+		const validationWarnings = out.warnings.filter((w) => w.startsWith("Validation:"));
+		expect(validationWarnings).toEqual([]);
+	});
+
+	it("rejects empty idVariable rather than rendering $: ID!", async () => {
+		await expect(
+			buildDetail({ org: ORG, object: "Account", fields: ["Id"], idVariable: "" }, noopPrimeDeps()),
+		).rejects.toThrow(/idVariable must be a non-empty string/);
+	});
+
+	it("throws when idVariable collides with a $varName already promoted by a child filter", async () => {
+		// User's child filter promotes `$id: String` (nullable, inferred). The
+		// default idVariable also wants `id` but as `ID!`. Without the guard,
+		// `addVariable` would silently overwrite the type and corrupt the
+		// child-filter binding.
+		await expect(
+			buildDetail(
+				{
+					org: ORG,
+					object: "Account",
+					fields: ["Id"],
+					childRelationships: [
+						{
+							relationshipName: "Contacts",
+							fields: ["Id"],
+							filter: { Title: { like: "$id" } },
+						},
+					],
+				},
+				noopPrimeDeps(),
+			),
+		).rejects.toThrow(/idVariable "id" collides with a \$id reference/);
+	});
+
+	it("does NOT throw when same name appears as ID! (e.g., user explicitly references $id in a child filter as the same record)", async () => {
+		// The collision guard fires only when the existing type differs from `ID!`.
+		// A child filter that references the *same* `$id` is unusual but legal.
+		// This test pins that we don't over-trigger.
+		const out = await buildDetail(
+			{ org: ORG, object: "Account", fields: ["Id"], idVariable: "accountId" },
+			noopPrimeDeps(),
+		);
+		expect(out.variables.find((v) => v.name === "accountId")?.type).toBe("ID!");
+	});
+
+	it("threads instanceUrl as 3rd arg to createSession", async () => {
+		const spy = vi.mocked(sessionModule.createSession);
+		spy.mockClear();
+		await buildDetail({ org: ORG, object: "Account", fields: ["Id", "Name"] }, noopPrimeDeps());
+		expect(spy).toHaveBeenCalledWith(ORG, "query", ORG_URL);
+	});
+});