@salesforce/graphiti 10.10.2

package/src/lib/session.ts

@@ -0,0 +1,1304 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import crypto from "crypto";
+import fs from "fs";
+import path from "path";
+import { graphitiHome } from "./fs-utils.js";
+
+// Evaluated lazily so that GRAPHITI_SESSIONS_DIR (or GRAPHITI_HOME) set in
+// tests takes effect even when the module is imported before the env var
+// is assigned.
+function getSessionsDir(): string {
+	return process.env.GRAPHITI_SESSIONS_DIR ?? path.join(graphitiHome(), "sessions");
+}
+
+export interface DirectiveNode {
+	name: string;
+	args: Record<string, string>;
+}
+
+export interface VariableDefinition {
+	name: string;
+	type: string;
+	defaultValue?: string;
+	runtimeValue?: string;
+}
+
+export interface BaseProjectionNode {
+	id: string;
+	kind: "field" | "fragment";
+	parentId: string | null;
+	schemaPath: string[];
+	directives: DirectiveNode[];
+}
+
+export interface FieldProjectionNode extends BaseProjectionNode {
+	kind: "field";
+	fieldName: string;
+	alias?: string;
+	args: Record<string, string>;
+}
+
+export interface FragmentProjectionNode extends BaseProjectionNode {
+	kind: "fragment";
+	onType: string;
+}
+
+export type ProjectionNode = FieldProjectionNode | FragmentProjectionNode;
+
+export type OperationType = "query" | "mutation" | "aggregate";
+
+export interface QuerySession {
+	id: string;
+	name?: string;
+	/** GraphQL operation name emitted by `renderQuery`. Distinct from `name`, which is the session's user-facing label. */
+	operationName?: string;
+	orgAlias: string;
+	/** Resolved Salesforce instance URL stored at session creation to avoid repeated sf-auth calls. */
+	instanceUrl?: string;
+	operation: OperationType;
+	navigationPath: string[];
+	nodes: ProjectionNode[];
+	variables: VariableDefinition[];
+	focusByPath: Record<string, string>;
+	createdAt: string;
+	undoStack?: string[];
+}
+
+const UNDO_STACK_LIMIT = 20;
+
+/**
+ * Snapshots the current session state (excluding undoStack) and pushes it
+ * onto the undo stack. Call this before any state-mutating operation.
+ */
+export function pushUndoSnapshot(session: QuerySession): void {
+	if (!session.undoStack) session.undoStack = [];
+	const { undoStack, ...rest } = session;
+	session.undoStack.push(JSON.stringify(rest));
+	if (session.undoStack.length > UNDO_STACK_LIMIT) {
+		session.undoStack.shift();
+	}
+}
+
+/**
+ * Pops the most recent undo snapshot and returns a restored session.
+ * The restored session inherits the current (truncated) undo stack.
+ * Returns null if there is nothing to undo.
+ */
+export function popUndo(session: QuerySession): QuerySession | null {
+	if (!session.undoStack || session.undoStack.length === 0) return null;
+	const snapshot = session.undoStack.pop()!;
+	const restored: QuerySession = JSON.parse(snapshot);
+	restored.undoStack = session.undoStack;
+	return restored;
+}
+
+export function isFragmentSegment(segment: string): boolean {
+	return (segment.startsWith("[") && segment.endsWith("]")) || segment.startsWith("on:");
+}
+
+/**
+ * Normalizes a fragment segment to the canonical `[Type]` form.
+ * Accepts `on:Type` as a shell-safe alternative that avoids zsh glob/redirect
+ * issues with `[Type]` and `<Type>`.
+ *
+ * Examples: `on:User` → `[User]`, `[User]` stays as-is.
+ */
+export function normalizeFragmentSegment(segment: string): string {
+	if (segment.startsWith("on:")) {
+		return `[${segment.slice(3)}]`;
+	}
+	return segment;
+}
+
+/** Returns true for alias-encoded path segments like `openOpps(Opportunity)`. */
+export function isAliasedSegment(segment: string): boolean {
+	return /^[^[\](]+\([^()]+\)$/.test(segment);
+}
+
+/**
+ * Parses an alias-encoded segment into its alias name and underlying field name.
+ * Returns null for plain or fragment segments.
+ */
+export function parseAliasedSegment(segment: string): { alias: string; fieldName: string } | null {
+	const m = segment.match(/^([^[\](]+)\(([^()]+)\)$/);
+	if (!m) return null;
+	return { alias: m[1], fieldName: m[2] };
+}
+
+/** Strips the alias wrapper from a single path segment, leaving just the schema field name. */
+export function schemaSegment(segment: string): string {
+	return parseAliasedSegment(segment)?.fieldName ?? segment;
+}
+
+/**
+ * Converts a navigation path (which may contain alias-encoded segments) to a
+ * pure schema path suitable for schema resolution and focus-map lookups.
+ */
+export function toSchemaPath(navPath: string[]): string[] {
+	return navPath.map(schemaSegment);
+}
+
+export function pathKey(pathSegments: string[]): string {
+	return pathSegments.join("/");
+}
+
+export function formatPath(pathSegments: string[]): string {
+	if (pathSegments.length === 0) return "/";
+	return `/${pathSegments.join("/")}`;
+}
+
+function randomId(prefix: string): string {
+	return `${prefix}_${crypto.randomBytes(4).toString("hex")}`;
+}
+
+function normalizeVariableName(name: string): string {
+	return name.replace(/^\$/, "");
+}
+
+export function createSession(
+	orgAlias: string,
+	operation: OperationType = "query",
+	instanceUrl?: string,
+	name?: string,
+): QuerySession {
+	return {
+		id: `s_${crypto.randomBytes(2).toString("hex")}`,
+		name,
+		orgAlias,
+		instanceUrl,
+		operation,
+		navigationPath: [],
+		nodes: [],
+		variables: [],
+		focusByPath: {},
+		createdAt: new Date().toISOString(),
+	};
+}
+
+export function cloneSession(source: QuerySession, newName?: string): QuerySession {
+	const cloned: QuerySession = JSON.parse(JSON.stringify(source));
+	cloned.id = `s_${crypto.randomBytes(2).toString("hex")}`;
+	cloned.name = newName;
+	cloned.createdAt = new Date().toISOString();
+	cloned.undoStack = [];
+	return cloned;
+}
+
+export function getNodeById(
+	session: QuerySession,
+	id: string | null | undefined,
+): ProjectionNode | null {
+	if (!id) return null;
+	return session.nodes.find((node) => node.id === id) ?? null;
+}
+
+export function getChildren(session: QuerySession, parentId: string | null): ProjectionNode[] {
+	return session.nodes.filter((node) => node.parentId === parentId);
+}
+
+function clearFocusBelow(session: QuerySession, schemaPath: string[]): void {
+	const prefix = pathKey(schemaPath);
+	for (const key of Object.keys(session.focusByPath)) {
+		if (key === prefix) continue;
+		if (prefix === "" || key.startsWith(`${prefix}/`)) {
+			delete session.focusByPath[key];
+		}
+	}
+}
+
+function createFieldNode(
+	parentId: string | null,
+	schemaPath: string[],
+	fieldName: string,
+	alias?: string,
+): FieldProjectionNode {
+	return {
+		id: randomId("fld"),
+		kind: "field",
+		parentId,
+		schemaPath: [...schemaPath],
+		fieldName,
+		alias,
+		args: {},
+		directives: [],
+	};
+}
+
+function createFragmentNode(
+	parentId: string | null,
+	schemaPath: string[],
+	onType: string,
+): FragmentProjectionNode {
+	return {
+		id: randomId("frag"),
+		kind: "fragment",
+		parentId,
+		schemaPath: [...schemaPath],
+		onType,
+		directives: [],
+	};
+}
+
+function matchNodeToSegment(node: ProjectionNode, segment: string): boolean {
+	if (node.kind === "fragment") {
+		return segment === `[${node.onType}]`;
+	}
+	return node.fieldName === segment;
+}
+
+export function listInstancesAtPath(session: QuerySession, schemaPath: string[]): ProjectionNode[] {
+	const parentPath = schemaPath.slice(0, -1);
+	const parentNode = getFocusedNodeAtPath(session, parentPath, false);
+	const parentId = parentNode?.id ?? null;
+	const segment = schemaPath[schemaPath.length - 1];
+	if (!segment) return [];
+	return getChildren(session, parentId).filter((node) => matchNodeToSegment(node, segment));
+}
+
+function resolveNodeAtPathInternal(
+	session: QuerySession,
+	schemaPath: string[],
+	createMissing: boolean,
+): ProjectionNode | null {
+	let parentId: string | null = null;
+	let current: ProjectionNode | null = null;
+
+	for (let i = 0; i < schemaPath.length; i += 1) {
+		const currentPath = schemaPath.slice(0, i + 1);
+		const currentKey = pathKey(currentPath);
+		const segment = schemaPath[i];
+		const matching: ProjectionNode[] = getChildren(session, parentId).filter(
+			(node: ProjectionNode) => matchNodeToSegment(node, segment),
+		);
+
+		const focusedId = session.focusByPath[currentKey];
+		let next: ProjectionNode | null =
+			matching.find((node: ProjectionNode) => node.id === focusedId) ?? null;
+
+		if (!next && matching.length === 1) {
+			next = matching[0];
+		}
+
+		if (!next && matching.length > 1 && !createMissing) {
+			throw new Error(
+				`Path ${formatPath(currentPath)} has multiple projection instances. Use \`cd <alias>(<field>)\` to navigate into one.`,
+			);
+		}
+
+		if (!next && createMissing) {
+			next = isFragmentSegment(segment)
+				? createFragmentNode(parentId, currentPath, segment.slice(1, -1))
+				: createFieldNode(parentId, currentPath, segment);
+			session.nodes.push(next);
+		}
+
+		if (!next) return null;
+
+		session.focusByPath[currentKey] = next.id;
+		parentId = next.id;
+		current = next;
+	}
+
+	return current;
+}
+
+export function getFocusedNodeAtPath(
+	session: QuerySession,
+	schemaPath: string[],
+	createMissing = false,
+): ProjectionNode | null {
+	if (schemaPath.length === 0) return null;
+	return resolveNodeAtPathInternal(session, schemaPath, createMissing);
+}
+
+export function ensureFocusedChain(
+	session: QuerySession,
+	schemaPath: string[],
+): ProjectionNode | null {
+	return getFocusedNodeAtPath(session, schemaPath, true);
+}
+
+/**
+ * Walks the query portion of the navigation path and syncs focusByPath entries
+ * for any aliased segments (e.g. `recentAccounts(Account)`). This ensures that
+ * subsequent select/assign operations target the correct aliased instance.
+ */
+export function syncFocusFromNavigationPath(session: QuerySession): void {
+	const ctx = getNavigationContext(session.navigationPath);
+	if (ctx !== "query") return;
+
+	const queryIdx = 0;
+	let parentId: string | null = null;
+
+	for (let i = queryIdx + 1; i < session.navigationPath.length; i++) {
+		const seg = session.navigationPath[i];
+		if (isArgsSegment(seg)) break;
+
+		const schemaPath = toSchemaPath(session.navigationPath.slice(queryIdx + 1, i + 1));
+		const key = pathKey(schemaPath);
+		const aliased = parseAliasedSegment(seg);
+
+		if (aliased) {
+			const aliasMatches: FieldProjectionNode[] = getChildren(session, parentId).filter(
+				(n): n is FieldProjectionNode =>
+					n.kind === "field" && n.fieldName === aliased.fieldName && n.alias === aliased.alias,
+			);
+			if (aliasMatches.length === 1) {
+				session.focusByPath[key] = aliasMatches[0].id;
+				parentId = aliasMatches[0].id;
+				continue;
+			}
+		}
+
+		const focusedId = session.focusByPath[key];
+		const fieldName = aliased ? aliased.fieldName : seg;
+		const fieldMatches: FieldProjectionNode[] = getChildren(session, parentId).filter(
+			(n): n is FieldProjectionNode => n.kind === "field" && n.fieldName === fieldName,
+		);
+		const focusedMatch = fieldMatches.find((n: FieldProjectionNode) => n.id === focusedId);
+		parentId = focusedMatch?.id ?? fieldMatches[0]?.id ?? null;
+	}
+}
+
+export function focusNodeAtPath(session: QuerySession, schemaPath: string[], nodeId: string): void {
+	const node = getNodeById(session, nodeId);
+	if (!node) throw new Error(`Projection instance "${nodeId}" not found.`);
+	if (pathKey(node.schemaPath) !== pathKey(schemaPath)) {
+		throw new Error(`Projection instance "${nodeId}" is not at ${formatPath(schemaPath)}.`);
+	}
+	session.focusByPath[pathKey(schemaPath)] = nodeId;
+	clearFocusBelow(session, schemaPath);
+}
+
+export function createSiblingFieldInstance(
+	session: QuerySession,
+	schemaPath: string[],
+	alias?: string,
+): FieldProjectionNode {
+	if (schemaPath.length === 0) {
+		throw new Error("Cannot create a projection instance at the root path.");
+	}
+	const parentPath = schemaPath.slice(0, -1);
+	const parentNode = ensureFocusedChain(session, parentPath);
+	const parentId = parentNode?.id ?? null;
+	const fieldName = schemaPath[schemaPath.length - 1];
+	if (isFragmentSegment(fieldName)) {
+		throw new Error("Use fragment navigation to create fragment projections.");
+	}
+	const node = createFieldNode(parentId, schemaPath, fieldName, alias);
+	session.nodes.push(node);
+	focusNodeAtPath(session, schemaPath, node.id);
+	return node;
+}
+
+export function setAliasOnPath(
+	session: QuerySession,
+	schemaPath: string[],
+	aliasName: string,
+): FieldProjectionNode {
+	const node = getFocusedNodeAtPath(session, schemaPath, true);
+	if (!node || node.kind !== "field") {
+		throw new Error(`No field projection exists at ${formatPath(schemaPath)}.`);
+	}
+	node.alias = aliasName;
+	focusNodeAtPath(session, schemaPath, node.id);
+	return node;
+}
+
+export function clearAliasOnPath(session: QuerySession, schemaPath: string[]): void {
+	const node = getFocusedNodeAtPath(session, schemaPath, false);
+	if (!node || node.kind !== "field") {
+		throw new Error(`No field projection exists at ${formatPath(schemaPath)}.`);
+	}
+	delete node.alias;
+}
+
+export function focusInstanceByAliasOrId(
+	session: QuerySession,
+	schemaPath: string[],
+	selector: string,
+): ProjectionNode {
+	const matches = listInstancesAtPath(session, schemaPath).filter((node) => {
+		if (node.id === selector) return true;
+		return node.kind === "field" && node.alias === selector;
+	});
+	if (matches.length === 0) {
+		throw new Error(
+			`No projection instance matching "${selector}" exists at ${formatPath(schemaPath)}.`,
+		);
+	}
+	if (matches.length > 1) {
+		throw new Error(
+			`Multiple projection instances match "${selector}" at ${formatPath(schemaPath)}.`,
+		);
+	}
+	focusNodeAtPath(session, schemaPath, matches[0].id);
+	return matches[0];
+}
+
+export function setArg(
+	session: QuerySession,
+	schemaPath: string[],
+	argName: string,
+	value: string,
+): void {
+	const node = getFocusedNodeAtPath(session, schemaPath, true);
+	if (!node || node.kind !== "field") {
+		throw new Error(`No field projection exists at ${formatPath(schemaPath)}.`);
+	}
+	node.args[argName] = value;
+}
+
+export function getArg(
+	session: QuerySession,
+	schemaPath: string[],
+	argName: string,
+): string | undefined {
+	const node = getFocusedNodeAtPath(session, schemaPath, false);
+	if (!node || node.kind !== "field") return undefined;
+	return node.args[argName];
+}
+
+export function removeArg(session: QuerySession, schemaPath: string[], argName: string): boolean {
+	const node = getFocusedNodeAtPath(session, schemaPath, false);
+	if (!node || node.kind !== "field") return false;
+	if (!(argName in node.args)) return false;
+	delete node.args[argName];
+	return true;
+}
+
+export function getEffectiveArgs(
+	_session: QuerySession,
+	node: ProjectionNode,
+): Record<string, string> {
+	if (node.kind !== "field") return {};
+	return { ...node.args };
+}
+
+// ── Navigation context helpers ───────────────────────────────────────────────
+
+export type NavigationContext = "root" | "query" | "variables";
+
+export function getNavigationContext(navPath: string[]): NavigationContext {
+	if (navPath.length === 0) return "root";
+	if (navPath[0] === "variables") return "variables";
+	return "query";
+}
+
+export const ARGS_SEGMENT = "@args";
+
+export function isArgsSegment(segment: string): boolean {
+	return segment === ARGS_SEGMENT;
+}
+
+/** Returns the index of the @args segment in the path, or -1 if not present. */
+export function argsSegmentIndex(navPath: string[]): number {
+	return navPath.indexOf(ARGS_SEGMENT);
+}
+
+/** Returns true if the navigation path is inside an @args context. */
+export function isInArgsContext(navPath: string[]): boolean {
+	return argsSegmentIndex(navPath) !== -1;
+}
+
+/**
+ * Extracts the schema path of the field whose args are being navigated.
+ * E.g. ["query", "uiapi", "query", "Account", "@args", "where", "Name"]
+ *   → ["uiapi", "query", "Account"]
+ */
+export function getArgsFieldPath(navPath: string[]): string[] {
+	const idx = argsSegmentIndex(navPath);
+	if (idx === -1) return [];
+	const queryPath = navPath.slice(1, idx);
+	return toSchemaPath(queryPath);
+}
+
+/**
+ * Extracts the input sub-path after @args.
+ * E.g. ["query", "uiapi", "query", "Account", "@args", "where", "Name"]
+ *   → ["where", "Name"]
+ */
+export function getInputSubPath(navPath: string[]): string[] {
+	const idx = argsSegmentIndex(navPath);
+	if (idx === -1) return [];
+	return navPath.slice(idx + 1);
+}
+
+/**
+ * For paths in the /query context, strips the "query" prefix and alias wrappers
+ * to produce a pure schema path. Stops at @args if present.
+ * E.g. ["query", "uiapi", "query", "Account"] → ["uiapi", "query", "Account"]
+ */
+export function queryNavToSchemaPath(navPath: string[]): string[] {
+	const ctx = getNavigationContext(navPath);
+	if (ctx !== "query") return [];
+	const argsIdx = argsSegmentIndex(navPath);
+	const end = argsIdx !== -1 ? argsIdx : navPath.length;
+	return toSchemaPath(navPath.slice(1, end));
+}
+
+/**
+ * For paths in /variables, extracts the variable name (without $) and the
+ * sub-path into its input type.
+ */
+export function parseVariablePath(
+	navPath: string[],
+): { varName: string; inputSubPath: string[] } | null {
+	if (getNavigationContext(navPath) !== "variables") return null;
+	if (navPath.length < 2) return null;
+	const varName = normalizeVariableName(navPath[1]);
+	return { varName, inputSubPath: navPath.slice(2) };
+}
+
+// ── Deep-set helpers for incremental arg/variable assignment ─────────────────
+
+function deepSet(
+	obj: Record<string, unknown>,
+	pathSegments: string[],
+	value: unknown,
+): Record<string, unknown> {
+	if (pathSegments.length === 0) return obj;
+	const result = { ...obj };
+	let current: Record<string, unknown> = result;
+
+	for (let i = 0; i < pathSegments.length - 1; i++) {
+		const seg = pathSegments[i];
+		const nextSeg = pathSegments[i + 1];
+		const nextIsIndex = nextSeg !== undefined && /^\d+$/.test(nextSeg);
+		if (/^\d+$/.test(seg)) {
+			const idx = Number(seg);
+			if (!Array.isArray(current)) {
+				throw new Error(`Expected array at path segment "${seg}"`);
+			}
+			const arr = current as unknown as unknown[];
+			while (arr.length <= idx) arr.push({});
+			if (typeof arr[idx] !== "object" || arr[idx] === null) arr[idx] = {};
+			current = arr[idx] as Record<string, unknown>;
+		} else {
+			if (current[seg] === undefined || current[seg] === null || typeof current[seg] !== "object") {
+				current[seg] = nextIsIndex ? [] : {};
+			} else if (nextIsIndex && !Array.isArray(current[seg])) {
+				current[seg] = [];
+			} else if (!Array.isArray(current[seg])) {
+				current[seg] = { ...(current[seg] as Record<string, unknown>) };
+			}
+			current = current[seg] as Record<string, unknown>;
+		}
+	}
+
+	const lastSeg = pathSegments[pathSegments.length - 1];
+	if (/^\d+$/.test(lastSeg)) {
+		const idx = Number(lastSeg);
+		if (!Array.isArray(current)) {
+			throw new Error(`Expected array at path segment "${lastSeg}"`);
+		}
+		(current as unknown as unknown[])[idx] = value;
+	} else {
+		current[lastSeg] = value;
+	}
+
+	return result;
+}
+
+function deepGet(obj: Record<string, unknown>, pathSegments: string[]): unknown {
+	let current: unknown = obj;
+	for (const seg of pathSegments) {
+		if (current === null || current === undefined) return undefined;
+		if (/^\d+$/.test(seg)) {
+			if (!Array.isArray(current)) return undefined;
+			current = (current as unknown[])[Number(seg)];
+		} else {
+			if (typeof current !== "object") return undefined;
+			current = (current as Record<string, unknown>)[seg];
+		}
+	}
+	return current;
+}
+
+function deepDelete(obj: Record<string, unknown>, pathSegments: string[]): Record<string, unknown> {
+	if (pathSegments.length === 0) return obj;
+	if (pathSegments.length === 1) {
+		const result = { ...obj };
+		delete result[pathSegments[0]];
+		return result;
+	}
+	const [head, ...rest] = pathSegments;
+	const child = obj[head];
+	if (typeof child !== "object" || child === null) return obj;
+	const result = { ...obj };
+	result[head] = deepDelete(child as Record<string, unknown>, rest);
+	return result;
+}
+
+function parseArgValue(raw: string): unknown {
+	const trimmed = raw.trim();
+	if (trimmed === "null") return null;
+	if (trimmed === "true") return true;
+	if (trimmed === "false") return false;
+	if (/^-?\d+(\.\d+)?$/.test(trimmed)) return Number(trimmed);
+	if (
+		(trimmed.startsWith("{") && trimmed.endsWith("}")) ||
+		(trimmed.startsWith("[") && trimmed.endsWith("]"))
+	) {
+		try {
+			return JSON.parse(trimmed);
+		} catch {
+			/* fall through */
+		}
+	}
+	if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
+		try {
+			return JSON.parse(trimmed);
+		} catch {
+			/* fall through */
+		}
+	}
+	return trimmed;
+}
+
+/**
+ * Incrementally sets a value deep inside a field argument's JSON structure.
+ * If inputPath is empty, sets the top-level arg directly.
+ * E.g. deepSetArg(session, path, "where", ["Name", "like"], '"Acme%"')
+ * results in node.args["where"] = '{"Name":{"like":"Acme%"}}'
+ */
+export function deepSetArg(
+	session: QuerySession,
+	schemaPath: string[],
+	argName: string,
+	inputPath: string[],
+	value: string,
+): void {
+	const node = getFocusedNodeAtPath(session, schemaPath, true);
+	if (!node || node.kind !== "field") {
+		throw new Error(`No field projection exists at ${formatPath(schemaPath)}.`);
+	}
+
+	if (inputPath.length === 0) {
+		node.args[argName] = value;
+		return;
+	}
+
+	const existing = node.args[argName];
+	let obj: Record<string, unknown> = {};
+	if (existing) {
+		try {
+			obj = JSON.parse(existing) as Record<string, unknown>;
+		} catch {
+			obj = {};
+		}
+	}
+
+	const parsedValue = value.startsWith("$") ? value : parseArgValue(value);
+	obj = deepSet(obj, inputPath, parsedValue);
+	node.args[argName] = JSON.stringify(obj);
+}
+
+/**
+ * Reads the current value at a nested path inside a field argument.
+ */
+export function deepGetArg(
+	session: QuerySession,
+	schemaPath: string[],
+	argName: string,
+	inputPath: string[],
+): unknown {
+	const node = getFocusedNodeAtPath(session, schemaPath, false);
+	if (!node || node.kind !== "field") return undefined;
+	const raw = node.args[argName];
+	if (raw === undefined) return undefined;
+	if (inputPath.length === 0) return raw;
+	try {
+		const obj = JSON.parse(raw);
+		return deepGet(obj, inputPath);
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Removes a value at a nested path inside a field argument.
+ */
+export function deepRemoveArg(
+	session: QuerySession,
+	schemaPath: string[],
+	argName: string,
+	inputPath: string[],
+): boolean {
+	const node = getFocusedNodeAtPath(session, schemaPath, false);
+	if (!node || node.kind !== "field") return false;
+
+	if (inputPath.length === 0) {
+		if (!(argName in node.args)) return false;
+		delete node.args[argName];
+		return true;
+	}
+
+	const raw = node.args[argName];
+	if (!raw) return false;
+	try {
+		let obj = JSON.parse(raw) as Record<string, unknown>;
+		obj = deepDelete(obj, inputPath);
+		if (Object.keys(obj).length === 0) {
+			delete node.args[argName];
+		} else {
+			node.args[argName] = JSON.stringify(obj);
+		}
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Incrementally sets a value deep inside a variable's runtime value.
+ * If inputPath is empty, sets the runtime value directly.
+ */
+export function deepSetVariableValue(
+	session: QuerySession,
+	varName: string,
+	inputPath: string[],
+	value: string,
+): void {
+	const cleanName = normalizeVariableName(varName);
+	const variable = session.variables.find((v) => v.name === cleanName);
+	if (!variable) throw new Error(`Variable "$${cleanName}" is not defined.`);
+
+	if (inputPath.length === 0) {
+		variable.runtimeValue = value;
+		return;
+	}
+
+	let obj: Record<string, unknown> = {};
+	if (variable.runtimeValue) {
+		try {
+			obj = JSON.parse(variable.runtimeValue) as Record<string, unknown>;
+		} catch {
+			obj = {};
+		}
+	}
+
+	const parsedValue = parseArgValue(value);
+	obj = deepSet(obj, inputPath, parsedValue);
+	variable.runtimeValue = JSON.stringify(obj);
+}
+
+/**
+ * Appends a new empty object to a list-type arg array. Returns the new index.
+ */
+export function appendListElement(
+	session: QuerySession,
+	schemaPath: string[],
+	argName: string,
+	inputPath: string[],
+): number {
+	const node = getFocusedNodeAtPath(session, schemaPath, true);
+	if (!node || node.kind !== "field") {
+		throw new Error(`No field projection exists at ${formatPath(schemaPath)}.`);
+	}
+
+	if (inputPath.length === 0) {
+		const raw = node.args[argName];
+		let arr: unknown[] = [];
+		if (raw) {
+			try {
+				arr = JSON.parse(raw);
+			} catch {
+				arr = [];
+			}
+			if (!Array.isArray(arr)) arr = [];
+		}
+		arr.push({});
+		node.args[argName] = JSON.stringify(arr);
+		return arr.length - 1;
+	}
+
+	const raw = node.args[argName];
+	let obj: Record<string, unknown> = {};
+	if (raw) {
+		try {
+			obj = JSON.parse(raw) as Record<string, unknown>;
+		} catch {
+			obj = {};
+		}
+	}
+	let target = deepGet(obj, inputPath);
+	if (!Array.isArray(target)) target = [];
+	const arr = target as unknown[];
+	arr.push({});
+	obj = deepSet(obj, inputPath, arr);
+	node.args[argName] = JSON.stringify(obj);
+	return arr.length - 1;
+}
+
+/**
+ * Removes an element from a list-type arg by index and compacts remaining indices.
+ */
+export function removeListElement(
+	session: QuerySession,
+	schemaPath: string[],
+	argName: string,
+	inputPath: string[],
+	index: number,
+): boolean {
+	const node = getFocusedNodeAtPath(session, schemaPath, false);
+	if (!node || node.kind !== "field") return false;
+
+	const raw = node.args[argName];
+	if (!raw) return false;
+
+	try {
+		let obj: Record<string, unknown> | unknown[] = JSON.parse(raw);
+
+		if (inputPath.length === 0) {
+			if (!Array.isArray(obj)) return false;
+			if (index < 0 || index >= obj.length) return false;
+			obj.splice(index, 1);
+			if (obj.length === 0) {
+				delete node.args[argName];
+			} else {
+				node.args[argName] = JSON.stringify(obj);
+			}
+			return true;
+		}
+
+		const parent = deepGet(obj as Record<string, unknown>, inputPath);
+		if (!Array.isArray(parent)) return false;
+		if (index < 0 || index >= parent.length) return false;
+		parent.splice(index, 1);
+		if (parent.length === 0) {
+			obj = deepDelete(obj as Record<string, unknown>, inputPath);
+		} else {
+			obj = deepSet(obj as Record<string, unknown>, inputPath, parent);
+		}
+		node.args[argName] = JSON.stringify(obj);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export function selectLeaf(
+	session: QuerySession,
+	schemaPath: string[],
+	alias?: string,
+): FieldProjectionNode {
+	if (schemaPath.length === 0) {
+		throw new Error("Cannot select the root path.");
+	}
+	const parentPath = schemaPath.slice(0, -1);
+	const parentNode = ensureFocusedChain(session, parentPath);
+	const parentId = parentNode?.id ?? null;
+	const fieldName = schemaPath[schemaPath.length - 1];
+	if (isFragmentSegment(fieldName)) {
+		throw new Error("Cannot select a fragment directory as a leaf.");
+	}
+
+	const siblings = getChildren(session, parentId).filter(
+		(node) => node.kind === "field" && node.fieldName === fieldName,
+	) as FieldProjectionNode[];
+
+	const existing = siblings.find((node) => node.alias === alias);
+	if (existing) {
+		focusNodeAtPath(session, schemaPath, existing.id);
+		return existing;
+	}
+
+	const node = createFieldNode(parentId, schemaPath, fieldName, alias);
+	session.nodes.push(node);
+	session.focusByPath[pathKey(schemaPath)] = node.id;
+	return node;
+}
+
+function removeNodeRecursive(session: QuerySession, nodeId: string): void {
+	const children = getChildren(session, nodeId);
+	for (const child of children) {
+		removeNodeRecursive(session, child.id);
+	}
+	session.nodes = session.nodes.filter((node) => node.id !== nodeId);
+	for (const [key, focusedId] of Object.entries(session.focusByPath)) {
+		if (focusedId === nodeId) {
+			delete session.focusByPath[key];
+		}
+	}
+}
+
+function pruneEmptyAncestors(session: QuerySession, startParentId: string | null): void {
+	let currentId = startParentId;
+	while (currentId) {
+		const current = getNodeById(session, currentId);
+		if (!current) return;
+		if (getChildren(session, current.id).length > 0) return;
+		const parentId = current.parentId;
+		removeNodeRecursive(session, current.id);
+		currentId = parentId;
+	}
+}
+
+export function removeSelectionAtPath(
+	session: QuerySession,
+	schemaPath: string[],
+	selector?: string,
+): boolean {
+	const parentPath = schemaPath.slice(0, -1);
+	const parentNode = getFocusedNodeAtPath(session, parentPath, false);
+	const parentId = parentNode?.id ?? null;
+	const segment = schemaPath[schemaPath.length - 1];
+	if (!segment) return false;
+
+	const matches = getChildren(session, parentId).filter((node) => {
+		if (!matchNodeToSegment(node, segment)) return false;
+		if (!selector) return true;
+		if (node.id === selector) return true;
+		return node.kind === "field" && node.alias === selector;
+	});
+
+	if (matches.length === 0) return false;
+	if (matches.length > 1) {
+		throw new Error(
+			`Multiple projection instances match ${formatPath(schemaPath)}. Use an alias or instance id to remove one.`,
+		);
+	}
+
+	const target = matches[0];
+	const parentToPrune = target.parentId;
+	removeNodeRecursive(session, target.id);
+	pruneEmptyAncestors(session, parentToPrune);
+	return true;
+}
+
+export function findDescendantByAlias(
+	session: QuerySession,
+	parentId: string | null,
+	alias: string,
+): FieldProjectionNode | null {
+	const children = getChildren(session, parentId);
+	for (const child of children) {
+		if (child.kind === "field" && child.alias === alias) return child;
+		const found = findDescendantByAlias(session, child.id, alias);
+		if (found) return found;
+	}
+	return null;
+}
+
+export function removeNodeByIdWithPrune(session: QuerySession, nodeId: string): boolean {
+	const node = getNodeById(session, nodeId);
+	if (!node) return false;
+	const parentToPrune = node.parentId;
+	removeNodeRecursive(session, nodeId);
+	pruneEmptyAncestors(session, parentToPrune);
+	return true;
+}
+
+export function addVariable(
+	session: QuerySession,
+	name: string,
+	type: string,
+	defaultValue?: string,
+): void {
+	const cleanName = normalizeVariableName(name);
+	const existing = session.variables.find((variable) => variable.name === cleanName);
+	if (existing) {
+		existing.type = type;
+		existing.defaultValue = defaultValue;
+		return;
+	}
+	session.variables.push({ name: cleanName, type, defaultValue });
+}
+
+export function setVariableRuntimeValue(
+	session: QuerySession,
+	name: string,
+	runtimeValue: string,
+): void {
+	const cleanName = normalizeVariableName(name);
+	const variable = session.variables.find((item) => item.name === cleanName);
+	if (!variable) {
+		throw new Error(`Variable "$${cleanName}" is not defined.`);
+	}
+	variable.runtimeValue = runtimeValue;
+}
+
+export function setVariableDefault(
+	session: QuerySession,
+	name: string,
+	defaultValue: string | undefined,
+): void {
+	const cleanName = normalizeVariableName(name);
+	const variable = session.variables.find((item) => item.name === cleanName);
+	if (!variable) {
+		throw new Error(`Variable "$${cleanName}" is not defined.`);
+	}
+	variable.defaultValue = defaultValue;
+}
+
+/**
+ * Finds all arg paths where a variable is referenced.
+ * Returns entries like `["Account", "where"] → "$filter"` for display.
+ */
+export function findVariableReferences(
+	session: QuerySession,
+	varName: string,
+): { fieldPath: string[]; argName: string; subPath: string[] }[] {
+	const ref = `$${varName}`;
+	const results: { fieldPath: string[]; argName: string; subPath: string[] }[] = [];
+
+	for (const node of session.nodes) {
+		if (node.kind !== "field") continue;
+		for (const [argName, raw] of Object.entries(node.args)) {
+			if (raw === ref) {
+				results.push({ fieldPath: node.schemaPath, argName, subPath: [] });
+				continue;
+			}
+			if (raw.startsWith("{") || raw.startsWith("[")) {
+				try {
+					const parsed = JSON.parse(raw);
+					findRefPaths(parsed, ref, []).forEach((subPath) => {
+						results.push({ fieldPath: node.schemaPath, argName, subPath });
+					});
+				} catch {
+					/* not JSON */
+				}
+			}
+		}
+	}
+
+	return results;
+}
+
+function findRefPaths(value: unknown, ref: string, currentPath: string[]): string[][] {
+	if (value === ref) return [currentPath];
+	if (Array.isArray(value)) {
+		const paths: string[][] = [];
+		for (let i = 0; i < value.length; i++) {
+			paths.push(...findRefPaths(value[i], ref, [...currentPath, String(i)]));
+		}
+		return paths;
+	}
+	if (typeof value === "object" && value !== null) {
+		const paths: string[][] = [];
+		for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+			paths.push(...findRefPaths(v, ref, [...currentPath, k]));
+		}
+		return paths;
+	}
+	return [];
+}
+
+export function removeVariable(session: QuerySession, name: string): boolean {
+	const cleanName = normalizeVariableName(name);
+	const before = session.variables.length;
+	session.variables = session.variables.filter((variable) => variable.name !== cleanName);
+	if (session.variables.length === before) return false;
+	purgeVariableReferences(session, cleanName);
+	return true;
+}
+
+/**
+ * Removes all references to `$varName` from field arguments across the
+ * entire projection tree. Handles both top-level arg values (`"$x"`) and
+ * values nested inside JSON arg structures.
+ */
+function purgeVariableReferences(session: QuerySession, varName: string): void {
+	const ref = `$${varName}`;
+	for (const node of session.nodes) {
+		if (node.kind !== "field") continue;
+		for (const argKey of Object.keys(node.args)) {
+			const raw = node.args[argKey];
+			if (raw === ref) {
+				delete node.args[argKey];
+				continue;
+			}
+			if (raw.startsWith("{") || raw.startsWith("[")) {
+				try {
+					const parsed = JSON.parse(raw);
+					const cleaned = purgeVarFromValue(parsed, ref);
+					if (cleaned === undefined) {
+						delete node.args[argKey];
+					} else {
+						const updated = JSON.stringify(cleaned);
+						if (updated !== raw) node.args[argKey] = updated;
+					}
+				} catch {
+					/* not JSON, skip */
+				}
+			}
+		}
+	}
+}
+
+function purgeVarFromValue(value: unknown, ref: string): unknown {
+	if (value === ref) return undefined;
+	if (Array.isArray(value)) {
+		const filtered = value
+			.map((item) => purgeVarFromValue(item, ref))
+			.filter((item) => item !== undefined);
+		return filtered.length > 0 ? filtered : undefined;
+	}
+	if (typeof value === "object" && value !== null) {
+		const obj = value as Record<string, unknown>;
+		const result: Record<string, unknown> = {};
+		let hasKeys = false;
+		for (const [k, v] of Object.entries(obj)) {
+			const cleaned = purgeVarFromValue(v, ref);
+			if (cleaned !== undefined) {
+				result[k] = cleaned;
+				hasKeys = true;
+			}
+		}
+		return hasKeys ? result : undefined;
+	}
+	return value;
+}
+
+function parseVariableValue(raw: string): unknown {
+	const trimmed = raw.trim();
+	if (trimmed === "null") return null;
+	if (trimmed === "true") return true;
+	if (trimmed === "false") return false;
+	if (/^-?\d+(\.\d+)?$/.test(trimmed)) return Number(trimmed);
+	if (
+		(trimmed.startsWith("{") && trimmed.endsWith("}")) ||
+		(trimmed.startsWith("[") && trimmed.endsWith("]")) ||
+		(trimmed.startsWith('"') && trimmed.endsWith('"'))
+	) {
+		try {
+			return JSON.parse(trimmed);
+		} catch {
+			return trimmed;
+		}
+	}
+	return trimmed;
+}
+
+/**
+ * Builds the variables map for query execution.
+ * Priority: ad-hoc overrides > session runtimeValue > defaultValue.
+ */
+export function buildRuntimeVariables(
+	session: QuerySession,
+	overrides?: Record<string, string>,
+): Record<string, unknown> {
+	const variables: Record<string, unknown> = {};
+	for (const variable of session.variables) {
+		const override = overrides?.[variable.name];
+		if (override !== undefined) {
+			variables[variable.name] = parseVariableValue(override);
+			continue;
+		}
+		if (variable.runtimeValue !== undefined) {
+			variables[variable.name] = parseVariableValue(variable.runtimeValue);
+			continue;
+		}
+		if (variable.defaultValue !== undefined) {
+			variables[variable.name] = parseVariableValue(variable.defaultValue);
+		}
+	}
+	return variables;
+}
+
+function sessionPath(id: string): string {
+	return path.join(getSessionsDir(), `${id}.json`);
+}
+
+export function saveSession(session: QuerySession): void {
+	fs.mkdirSync(getSessionsDir(), { recursive: true });
+	fs.writeFileSync(sessionPath(session.id), JSON.stringify(session, null, 2), "utf-8");
+}
+
+function migrateSession(raw: Record<string, unknown>): QuerySession {
+	const navPath = (raw.navigationPath as string[]) ?? [];
+	// Auto-migrate old sessions: prepend "query" if the path doesn't start with "query" or "variables"
+	const migratedPath =
+		navPath.length > 0 && navPath[0] !== "query" && navPath[0] !== "variables"
+			? ["query", ...navPath]
+			: navPath;
+
+	return {
+		...(raw as unknown as QuerySession),
+		navigationPath: migratedPath,
+		nodes: (raw.nodes as ProjectionNode[]) ?? [],
+		variables: (raw.variables as VariableDefinition[]) ?? [],
+		focusByPath: (raw.focusByPath as Record<string, string>) ?? {},
+		undoStack: (raw.undoStack as string[]) ?? [],
+	};
+}
+
+export function loadSession(id: string): QuerySession {
+	if (!fs.existsSync(sessionPath(id))) {
+		const dir = getSessionsDir();
+		if (fs.existsSync(dir)) {
+			const files = fs.readdirSync(dir).filter((f) => f.endsWith(".json"));
+			for (const file of files) {
+				try {
+					const raw = JSON.parse(fs.readFileSync(path.join(dir, file), "utf-8"));
+					if (raw.name === id) return migrateSession(raw);
+				} catch {
+					/* skip */
+				}
+			}
+		}
+		throw new Error(
+			`Session "${id}" not found. Create one with \`graphiti query new <org-alias>\`.`,
+		);
+	}
+	const raw = JSON.parse(fs.readFileSync(sessionPath(id), "utf-8"));
+	return migrateSession(raw);
+}
+
+export function listSessions(): {
+	id: string;
+	name?: string;
+	orgAlias: string;
+	operation: string;
+	createdAt: string;
+}[] {
+	const dir = getSessionsDir();
+	if (!fs.existsSync(dir)) return [];
+	return fs
+		.readdirSync(dir)
+		.filter((fileName) => fileName.endsWith(".json"))
+		.map((fileName) => {
+			try {
+				const raw = JSON.parse(fs.readFileSync(path.join(dir, fileName), "utf-8"));
+				return {
+					id: raw.id,
+					name: raw.name,
+					orgAlias: raw.orgAlias,
+					operation: raw.operation,
+					createdAt: raw.createdAt,
+				};
+			} catch {
+				return null;
+			}
+		})
+		.filter((session): session is NonNullable<typeof session> => session !== null);
+}
+
+export function deleteSession(id: string): boolean {
+	const filePath = sessionPath(id);
+	if (fs.existsSync(filePath)) {
+		fs.unlinkSync(filePath);
+		return true;
+	}
+	const dir = getSessionsDir();
+	if (fs.existsSync(dir)) {
+		for (const file of fs.readdirSync(dir).filter((f) => f.endsWith(".json"))) {
+			try {
+				const raw = JSON.parse(fs.readFileSync(path.join(dir, file), "utf-8"));
+				if (raw.name === id) {
+					fs.unlinkSync(path.join(dir, file));
+					return true;
+				}
+			} catch {
+				/* skip */
+			}
+		}
+	}
+	return false;
+}