@salesforce/graphiti 10.10.2

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

@@ -0,0 +1,432 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import { rmSync } from "node:fs";
+import path from "node:path";
+import { buildSchema, introspectionFromSchema } from "graphql";
+import { describe, expect, it } from "vitest";
+import { atomicWriteJson } from "../../lib/fs-utils.js";
+import {
+	schemaCacheKeyForInstanceUrl,
+	schemaDir,
+	type SchemaMetadata,
+} from "../../lib/introspect.js";
+import { type FieldMetadata, type ObjectInfoResult } from "../../lib/object-info.js";
+import { type PrimeDeps } from "../../lib/prime-schema.js";
+import { primeSchemaCache } from "../../lib/walker.js";
+import { buildDiscover, type DiscoverDeps } from "../build-discover.js";
+
+const ORG = "test-discover";
+const ORG_URL = "https://test-discover.my.salesforce.com";
+
+const SCHEMA = buildSchema(`
+	type Query { uiapi: UIAPI! }
+	type UIAPI { query: RecordQuery! }
+
+	type RecordQuery {
+		"Customer accounts"
+		Account(first: Int, after: String): AccountConnection!
+		Case(first: Int, after: String): CaseConnection!
+		Contact(first: Int, after: String): ContactConnection!
+	}
+
+	type AccountConnection { edges: [AccountEdge!]! }
+	type AccountEdge { node: Account! }
+	type Account { Id: ID!, Name: StringValue }
+
+	type CaseConnection { edges: [CaseEdge!]! }
+	type CaseEdge { node: Case! }
+	type Case { Id: ID!, Subject: StringValue }
+
+	type ContactConnection { edges: [ContactEdge!]! }
+	type ContactEdge { node: Contact! }
+	type Contact { Id: ID!, LastName: StringValue }
+
+	type StringValue { value: String }
+`);
+
+primeSchemaCache(ORG, SCHEMA);
+primeSchemaCache(ORG_URL, SCHEMA);
+
+function makePrimeDeps(): 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;
+		},
+	};
+}
+
+function makeField(overrides: Partial<FieldMetadata>): FieldMetadata {
+	return {
+		apiName: "Field",
+		label: "Field",
+		dataType: "STRING",
+		required: false,
+		createable: false,
+		updateable: false,
+		calculated: false,
+		custom: false,
+		filterable: true,
+		sortable: true,
+		nameField: false,
+		reference: false,
+		relationshipName: null,
+		compound: false,
+		compoundFieldName: null,
+		defaultedOnCreate: false,
+		extraTypeInfo: null,
+		inlineHelpText: null,
+		precision: 0,
+		scale: 0,
+		referenceToInfos: [],
+		controllerName: null,
+		controllingFields: [],
+		...overrides,
+	};
+}
+
+const ACCOUNT_INFO: ObjectInfoResult = {
+	apiName: "Account",
+	label: "Account",
+	labelPlural: "Accounts",
+	createable: true,
+	deletable: true,
+	updateable: true,
+	queryable: true,
+	searchable: true,
+	custom: false,
+	keyPrefix: "001",
+	nameFields: ["Name"],
+	defaultRecordTypeId: null,
+	fields: [
+		makeField({
+			apiName: "Id",
+			label: "Account ID",
+			dataType: "ID",
+			filterable: true,
+			sortable: true,
+			createable: false,
+			updateable: false,
+		}),
+		makeField({
+			apiName: "Name",
+			label: "Account Name",
+			dataType: "STRING",
+			nameField: true,
+			required: true,
+			createable: true,
+			updateable: true,
+		}),
+		makeField({
+			apiName: "Industry",
+			label: "Industry",
+			dataType: "PICKLIST",
+			createable: true,
+			updateable: true,
+		}),
+		makeField({
+			apiName: "OwnerId",
+			label: "Owner ID",
+			dataType: "REFERENCE",
+			reference: true,
+			relationshipName: "Owner",
+			referenceToInfos: [
+				{ apiName: "User", nameFields: ["Name"] },
+				{ apiName: "Group", nameFields: ["Name"] },
+			],
+			createable: true,
+			updateable: true,
+		}),
+		makeField({
+			apiName: "BillingAddress",
+			label: "Billing Address",
+			dataType: "ADDRESS",
+			compound: true,
+			filterable: false,
+			sortable: false,
+		}),
+		makeField({
+			apiName: "AutoNumber__c",
+			label: "Auto Number",
+			dataType: "STRING",
+			required: true,
+			createable: true,
+			defaultedOnCreate: true,
+		}),
+	],
+	childRelationships: [
+		{ childObjectApiName: "Contact", fieldName: "AccountId", relationshipName: "Contacts" },
+		{ childObjectApiName: "Case", fieldName: "AccountId", relationshipName: null },
+	],
+	recordTypeInfos: [],
+	picklists: [
+		{
+			apiName: "Industry",
+			label: "Industry",
+			required: false,
+			values: [
+				{ value: "Technology", label: "Technology" },
+				{ value: "Finance", label: "Finance" },
+			],
+		},
+	],
+	fetchedAt: new Date().toISOString(),
+};
+
+function makeDeps(): DiscoverDeps {
+	return {
+		primeDeps: makePrimeDeps(),
+		getOrgAuth: async () => ({
+			alias: ORG,
+			username: "u",
+			instanceUrl: ORG_URL,
+			accessToken: "t",
+			orgId: "00D",
+		}),
+		getObjectInfo: async (_auth, _alias, name) => {
+			if (name === "Account") return ACCOUNT_INFO;
+			throw new Error(`No fixture for ${name}`);
+		},
+	};
+}
+
+describe("intent/build-discover", () => {
+	describe("list_objects mode (FR-11.1)", () => {
+		it("returns queryable SObjects sorted alphabetically", async () => {
+			const out = await buildDiscover({ org: ORG, mode: "list_objects" }, makeDeps());
+			expect(out.mode).toBe("list_objects");
+			if (out.mode !== "list_objects") return;
+			expect(out.objects.map((o) => o.name)).toEqual(["Account", "Case", "Contact"]);
+		});
+
+		it("includes the schema description as the label when present", async () => {
+			const out = await buildDiscover({ org: ORG, mode: "list_objects" }, makeDeps());
+			if (out.mode !== "list_objects") return;
+			const account = out.objects.find((o) => o.name === "Account");
+			expect(account?.label).toBe("Customer accounts");
+		});
+
+		it("filters by search substring (case-insensitive)", async () => {
+			const out = await buildDiscover(
+				{ org: ORG, mode: "list_objects", search: "cas" },
+				makeDeps(),
+			);
+			if (out.mode !== "list_objects") return;
+			expect(out.objects.map((o) => o.name)).toEqual(["Case"]);
+		});
+
+		it("excludes non-Connection fields like search/aggregate helpers", async () => {
+			const ALIAS = "test-discover-helpers";
+			const URL = "https://test-discover-helpers.my.salesforce.com";
+			const helperSchema = buildSchema(`
+				type Query { uiapi: UIAPI! }
+				type UIAPI { query: RecordQuery! }
+				type RecordQuery {
+					Account(first: Int): AccountConnection!
+					search(term: String!): SearchResult!
+					aggregate: AggregateResult!
+				}
+				type AccountConnection { edges: [AccountEdge!]! }
+				type AccountEdge { node: Account! }
+				type Account { Id: ID! }
+				type SearchResult { hits: Int }
+				type AggregateResult { total: Int }
+			`);
+			primeSchemaCache(ALIAS, helperSchema);
+			primeSchemaCache(URL, helperSchema);
+
+			const helperDeps: DiscoverDeps = {
+				primeDeps: {
+					getOrgAuth: async () => ({
+						alias: ALIAS,
+						username: "u",
+						instanceUrl: URL,
+						accessToken: "t",
+						orgId: "00D",
+					}),
+					downloadSchema: async (auth) => {
+						const cacheKey = schemaCacheKeyForInstanceUrl(auth.instanceUrl);
+						const filePath = path.join(schemaDir(), `${cacheKey}.json`);
+						atomicWriteJson(filePath, { data: introspectionFromSchema(helperSchema) });
+						return {
+							cacheKey,
+							instanceUrl: auth.instanceUrl,
+							typeCount: 0,
+							downloadedAt: new Date().toISOString(),
+							filePath,
+						};
+					},
+				},
+			};
+
+			const out = await buildDiscover({ org: ALIAS, mode: "list_objects" }, helperDeps);
+			if (out.mode !== "list_objects") return;
+			expect(out.objects.map((o) => o.name)).toEqual(["Account"]);
+		});
+
+		it("surfaces the FR-13.3 priming note in warnings on cold prime", async () => {
+			const ALIAS = "test-discover-cold";
+			const URL = "https://test-discover-cold.my.salesforce.com";
+			const coldSchema = buildSchema(`
+				type Query { uiapi: UIAPI! }
+				type UIAPI { query: RecordQuery! }
+				type RecordQuery { Account(first: Int): AccountConnection! }
+				type AccountConnection { edges: [AccountEdge!]! }
+				type AccountEdge { node: Account! }
+				type Account { Id: ID! }
+			`);
+			primeSchemaCache(URL, coldSchema);
+
+			// downloadSchema below writes to the real ~/.graphiti/schemas/ dir.
+			// The "cold prime" assertion requires that cache file to be ABSENT so
+			// buildDiscover primes it and emits the FR-13.3 warning. A prior run
+			// of this test leaves the file behind, so on the next run the cache is
+			// already present, no priming happens, and the warning assertion fails.
+			// Clear it before (restore the cold precondition) and after (no leak).
+			const coldCachePath = path.join(schemaDir(), `${schemaCacheKeyForInstanceUrl(URL)}.json`);
+			rmSync(coldCachePath, { force: true });
+
+			const coldDeps: DiscoverDeps = {
+				primeDeps: {
+					getOrgAuth: async () => ({
+						alias: ALIAS,
+						username: "u",
+						instanceUrl: URL,
+						accessToken: "t",
+						orgId: "00D",
+					}),
+					downloadSchema: async (auth) => {
+						const cacheKey = schemaCacheKeyForInstanceUrl(auth.instanceUrl);
+						const filePath = path.join(schemaDir(), `${cacheKey}.json`);
+						atomicWriteJson(filePath, { data: introspectionFromSchema(coldSchema) });
+						return {
+							cacheKey,
+							instanceUrl: auth.instanceUrl,
+							typeCount: 0,
+							downloadedAt: new Date().toISOString(),
+							filePath,
+						};
+					},
+				},
+			};
+
+			try {
+				const out = await buildDiscover({ org: ALIAS, mode: "list_objects" }, coldDeps);
+				if (out.mode !== "list_objects") return;
+				expect(out.warnings).toBeDefined();
+				expect(out.warnings?.[0]).toMatch(/Primed schema cache for "test-discover-cold"/);
+			} finally {
+				rmSync(coldCachePath, { force: true });
+			}
+		});
+	});
+
+	describe("describe_object mode (FR-11.2)", () => {
+		it("returns object metadata with picklists, child relationships, parent refs", async () => {
+			const out = await buildDiscover(
+				{ org: ORG, mode: "describe_object", object: "Account" },
+				makeDeps(),
+			);
+			expect(out.mode).toBe("describe_object");
+			if (out.mode !== "describe_object") return;
+
+			expect(out.object.name).toBe("Account");
+			const fieldNames = out.object.fields.map((f) => f.name);
+			expect(fieldNames).toContain("Id");
+			expect(fieldNames).toContain("Name");
+
+			const industry = out.object.fields.find((f) => f.name === "Industry");
+			expect(industry?.picklistValues).toEqual(["Technology", "Finance"]);
+
+			expect(out.object.childRelationships).toEqual([
+				{ relationshipName: "Contacts", childObject: "Contact" },
+			]);
+
+			expect(out.object.parentReferences).toEqual([
+				{ field: "OwnerId", targetObjects: ["User", "Group"] },
+			]);
+		});
+
+		it("filterableFields excludes compound fields", async () => {
+			const out = await buildDiscover(
+				{ org: ORG, mode: "describe_object", object: "Account" },
+				makeDeps(),
+			);
+			if (out.mode !== "describe_object") return;
+			expect(out.object.filterableFields).not.toContain("BillingAddress");
+			expect(out.object.filterableFields).toContain("Name");
+		});
+
+		it("orderByExample uses the first sortable non-compound field", async () => {
+			const out = await buildDiscover(
+				{ org: ORG, mode: "describe_object", object: "Account" },
+				makeDeps(),
+			);
+			if (out.mode !== "describe_object") return;
+			expect(Object.keys(out.object.orderByExample)).toHaveLength(1);
+		});
+
+		it("requiredOnCreate excludes fields defaulted on create", async () => {
+			const out = await buildDiscover(
+				{ org: ORG, mode: "describe_object", object: "Account" },
+				makeDeps(),
+			);
+			if (out.mode !== "describe_object") return;
+			expect(out.object.requiredOnCreate).toEqual(["Name"]);
+		});
+
+		it("throws when object is missing", async () => {
+			await expect(
+				buildDiscover({ org: ORG, mode: "describe_object" }, makeDeps()),
+			).rejects.toThrow(/requires "object"/);
+		});
+	});
+
+	describe("describe_field mode (FR-11.3)", () => {
+		it("returns the named field's metadata", async () => {
+			const out = await buildDiscover(
+				{ org: ORG, mode: "describe_field", object: "Account", field: "Industry" },
+				makeDeps(),
+			);
+			expect(out.mode).toBe("describe_field");
+			if (out.mode !== "describe_field") return;
+			expect(out.field.name).toBe("Industry");
+			expect(out.field.picklistValues).toEqual(["Technology", "Finance"]);
+		});
+
+		it("throws when field is missing from spec", async () => {
+			await expect(
+				buildDiscover({ org: ORG, mode: "describe_field", object: "Account" }, makeDeps()),
+			).rejects.toThrow(/requires "field"/);
+		});
+
+		it("throws when field is not on the object", async () => {
+			await expect(
+				buildDiscover(
+					{ org: ORG, mode: "describe_field", object: "Account", field: "DoesNotExist" },
+					makeDeps(),
+				),
+			).rejects.toThrow(/not found on "Account"/);
+		});
+	});
+});

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

@@ -0,0 +1,284 @@
+/**
+ * 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 { buildList } from "../build-list.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! }
+
+	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 { Industry: PicklistOperators, Name: StringOperators }
+	input Account_OrderBy { Name: OrderByClause, Industry: OrderByClause }
+	input Case_Filter { Status: PicklistOperators, Priority: PicklistOperators }
+	input Case_OrderBy { CreatedDate: OrderByClause }
+	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 { 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-list";
+const ORG_URL = "https://test-list.my.salesforce.com";
+const SCHEMA = buildSchema(SCHEMA_SDL);
+// Prime the in-memory schema cache by both alias and URL so getSchema()
+// resolves either key without touching disk or the keychain.
+primeSchemaCache(ORG, SCHEMA);
+primeSchemaCache(ORG_URL, SCHEMA);
+
+const noopPrimeDeps = () => makeNoopPrimeDeps(ORG, ORG_URL, SCHEMA);
+
+describe("intent/build-list", () => {
+	it("scalar fields select { value } except Id (FR-4.1)", async () => {
+		const out = await buildList(
+			{ 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>List", async () => {
+		const out = await buildList({ org: ORG, object: "Case", fields: ["Id"] }, noopPrimeDeps());
+		expect(out.query).toMatch(/\bquery\s+CaseList\b/);
+	});
+
+	it("respects custom operationName", async () => {
+		const out = await buildList(
+			{ org: ORG, object: "Case", fields: ["Id"], operationName: "MyCases" },
+			noopPrimeDeps(),
+		);
+		expect(out.query).toMatch(/\bquery\s+MyCases\b/);
+	});
+
+	it("rejects an operationName that is not a valid GraphQL Name", async () => {
+		await expect(
+			buildList(
+				{ org: ORG, object: "Account", fields: ["Id"], operationName: "has spaces" },
+				noopPrimeDeps(),
+			),
+		).rejects.toThrow(/buildList: operationName 'has spaces' is not a valid GraphQL Name/);
+	});
+
+	it("rejects an object that is not a valid GraphQL Name", async () => {
+		await expect(
+			buildList({ org: ORG, object: "Order Item", fields: ["Id"] }, noopPrimeDeps()),
+		).rejects.toThrow(/buildList: object 'Order Item' is not a valid GraphQL Name/);
+	});
+
+	it("declares $after and selects pageInfo (FR-7)", async () => {
+		const out = await buildList({ org: ORG, object: "Case", fields: ["Id"] }, noopPrimeDeps());
+		expect(out.variables.find((v) => v.name === "after")).toBeDefined();
+		expect(out.query).toMatch(/\$after\s*:\s*String\b/);
+		expect(out.query).toMatch(/pageInfo\s*\{[^}]*hasNextPage[^}]*endCursor/s);
+		expect(out.query).toMatch(/first\s*:\s*10\b/);
+	});
+
+	it("parentFields walks dotted path with value wrapping (FR-4.2)", async () => {
+		const out = await buildList(
+			{ 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 buildList(
+			{ 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 buildList(
+			{ 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 (FR-4.4)", async () => {
+		const out = await buildList(
+			{
+				org: ORG,
+				object: "Account",
+				fields: ["Id"],
+				childRelationships: [
+					{ relationshipName: "Contacts", fields: ["Id", "LastName"], first: 5 },
+				],
+			},
+			noopPrimeDeps(),
+		);
+		expect(out.query).toMatch(/Contacts\s*\([^)]*first:\s*5/);
+		expect(out.query).toMatch(
+			/Contacts\s*\([^)]*\)\s*\{\s*edges\s*\{\s*node\s*\{[^}]*LastName\s*\{\s*value\s*\}/s,
+		);
+	});
+
+	it("filter with $varName promotes typed variable (FR-5.1, 5.2)", async () => {
+		const out = await buildList(
+			{
+				org: ORG,
+				object: "Case",
+				fields: ["Id"],
+				filter: { Status: { eq: "$status" } },
+			},
+			noopPrimeDeps(),
+		);
+		const status = out.variables.find((v) => v.name === "status");
+		expect(status).toBeDefined();
+		expect(status!.required).toBe(false);
+		expect(out.query).toMatch(/\$status\b/);
+	});
+
+	it("literal filter values are inlined, no variable promoted", async () => {
+		const out = await buildList(
+			{
+				org: ORG,
+				object: "Case",
+				fields: ["Id"],
+				filter: { Status: { eq: "New" } },
+			},
+			noopPrimeDeps(),
+		);
+		expect(out.variables.find((v) => v.name === "status")).toBeUndefined();
+		expect(out.query).toMatch(/Status\s*:\s*\{\s*eq\s*:\s*"New"/);
+	});
+
+	it("orderBy emitted as singleton object (FR-6.1)", async () => {
+		const out = await buildList(
+			{
+				org: ORG,
+				object: "Case",
+				fields: ["Id"],
+				orderBy: { CreatedDate: { order: "ASC" } },
+			},
+			noopPrimeDeps(),
+		);
+		expect(out.query).toMatch(/orderBy\s*:\s*\{\s*CreatedDate/);
+		expect(out.query).not.toMatch(/orderBy\s*:\s*\[/);
+	});
+
+	it("orderBy array is collapsed to first element (FR-6.2)", async () => {
+		const out = await buildList(
+			{
+				org: ORG,
+				object: "Account",
+				fields: ["Id"],
+				orderBy: [{ Name: { order: "ASC" } }, { Industry: { order: "DESC" } }],
+			},
+			noopPrimeDeps(),
+		);
+		expect(out.query).toMatch(/orderBy\s*:\s*\{\s*Name/);
+		expect(out.query).not.toMatch(/Industry/);
+	});
+
+	it("scope literal is set on connection", async () => {
+		const out = await buildList(
+			{ org: ORG, object: "Case", fields: ["Id"], scope: "MINE" },
+			noopPrimeDeps(),
+		);
+		expect(out.query).toMatch(/scope\s*:\s*MINE/);
+	});
+
+	it("$varName scope promotes a variable", async () => {
+		const out = await buildList(
+			{ org: ORG, object: "Case", fields: ["Id"], scope: "$myScope" },
+			noopPrimeDeps(),
+		);
+		expect(out.variables.find((v) => v.name === "myScope")).toBeDefined();
+		expect(out.query).toMatch(/scope\s*:\s*\$myScope/);
+	});
+
+	it("unresolvable filter input path falls back to String (FR-5.4)", async () => {
+		// `Account_Filter` has `Industry` and `Name`, but no `BogusField` —
+		// inferTypeFromArgsPath will throw, and promoteVariables falls back to String.
+		const out = await buildList(
+			{
+				org: ORG,
+				object: "Account",
+				fields: ["Id"],
+				filter: { BogusField: { eq: "$bogus" } },
+			},
+			noopPrimeDeps(),
+		);
+		const bogus = out.variables.find((v) => v.name === "bogus");
+		expect(bogus).toBeDefined();
+		expect(bogus!.type).toBe("String");
+	});
+
+	it("threads instanceUrl as 3rd arg to createSession", async () => {
+		const spy = vi.mocked(sessionModule.createSession);
+		spy.mockClear();
+		await buildList({ org: ORG, object: "Case", fields: ["Id"] }, noopPrimeDeps());
+		expect(spy).toHaveBeenCalledWith(ORG, "query", ORG_URL);
+	});
+});