java.ts

/*---------------------------------------------------------------------------------------------
 *  Copyright (c) Microsoft Corporation. All rights reserved.
 *--------------------------------------------------------------------------------------------*/

/**
 * Java code generator for session-events and RPC types.
 * Generates Java source files under sdk/src/generated/java/ from JSON Schema files.
 */

import fs from "fs/promises";
import { realpathSync } from "fs";
import type { JSONSchema7 } from "json-schema";
import path from "path";
import { fileURLToPath } from "url";
import { RPC_VARIANT_OWNERS } from "./rpc-variant-owners.js";
import { hasLegacyParameters, isOmittableRequest, LEGACY_PARAMETERS_KEY, readLegacyParameters, type LegacyParameters } from "../../../scripts/codegen/legacy-parameters.js";

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

/** Root of the copilot-sdk-java repo */
const REPO_ROOT = path.resolve(__dirname, "../..");
const OUTPUT_ROOT = process.env.COPILOT_CODEGEN_OUTPUT_ROOT ?? REPO_ROOT;

/** Event types to exclude from generation (internal/legacy types) */
const EXCLUDED_EVENT_TYPES = new Set(["session.import_legacy"]);

function isSchemaInternal(schema: JSONSchema7 | null | undefined): boolean {
    return typeof schema === "object" &&
        schema !== null &&
        (schema as Record<string, unknown>).visibility === "internal";
}

function isSchemaExperimental(schema: JSONSchema7 | null | undefined): boolean {
    return typeof schema === "object" &&
        schema !== null &&
        (schema as Record<string, unknown>).stability === "experimental";
}

function appendExperimentalTypeApiNote(lines: string[], schema: JSONSchema7): void {
    if (isSchemaExperimental(schema)) {
        lines.push(` *`);
        lines.push(` * @apiNote This type is experimental and may change in a future version.`);
    }
}

const AUTO_GENERATED_HEADER = `// AUTO-GENERATED FILE - DO NOT EDIT`;
const GENERATED_FROM_SESSION_EVENTS = `// Generated from: session-events.schema.json`;
const GENERATED_FROM_API = `// Generated from: api.schema.json`;
const GENERATED_ANNOTATION = `@javax.annotation.processing.Generated("copilot-sdk-codegen")`;
const COPYRIGHT = `/*---------------------------------------------------------------------------------------------\n *  Copyright (c) Microsoft Corporation. All rights reserved.\n *--------------------------------------------------------------------------------------------*/`;

// ── Naming utilities ─────────────────────────────────────────────────────────

/**
 * Correct the GitHub brand casing in a generated identifier or documentation
 * string. Schema titles/definition names and value-derived identifiers may
 * render the brand as "Github"; the correct casing is "GitHub". Lowercase
 * wire/protocol values (e.g. "github") are left untouched. Idempotent.
 */
function fixBrandCasing(value: string): string {
    return value.replace(/Github/g, "GitHub");
}

const BRAND_NORMALIZED_STRING_KEYS = new Set(["title", "description", "markdownDescription"]);

/**
 * Recursively normalize GitHub brand casing within a parsed JSON schema:
 * definition-map keys, `$ref` pointers (definition-name segment only), and
 * documentation strings. Wire-level values (`const`, `enum`, `default`, ...) are
 * left untouched. Mutates in place and returns the schema.
 */
function normalizeSchemaBrandCasing<T>(schema: T): T {
    normalizeBrandCasingNode(schema);
    return schema;
}

function normalizeBrandCasingNode(node: unknown): void {
    if (Array.isArray(node)) {
        for (const item of node) normalizeBrandCasingNode(item);
        return;
    }
    if (node === null || typeof node !== "object") return;
    const obj = node as Record<string, unknown>;

    if (obj.title === "ProviderModelConfig" && obj.properties && typeof obj.properties === "object") {
        const tokenFields = new Set([
            "maxPromptTokens",
            "maxContextWindowTokens",
            "maxOutputTokens",
        ]);
        for (const [key, value] of Object.entries(obj.properties as Record<string, unknown>)) {
            if (
                tokenFields.has(key) &&
                value !== null &&
                typeof value === "object" &&
                (value as Record<string, unknown>).type === "number"
            ) {
                (value as Record<string, unknown>).type = "integer";
            }
        }
    }

    for (const defsKey of ["definitions", "$defs"] as const) {
        const defs = obj[defsKey];
        if (defs && typeof defs === "object" && !Array.isArray(defs)) {
            renameBrandDefinitionKeys(defs as Record<string, unknown>);
        }
    }

    for (const [key, value] of Object.entries(obj)) {
        if (typeof value === "string") {
            if (key === "$ref") {
                obj[key] = fixBrandRef(value);
            } else if (BRAND_NORMALIZED_STRING_KEYS.has(key)) {
                obj[key] = fixBrandCasing(value);
            }
        } else {
            normalizeBrandCasingNode(value);
        }
    }
}

function fixBrandRef(ref: string): string {
    const lastSlash = ref.lastIndexOf("/");
    if (lastSlash === -1) return ref;
    return `${ref.slice(0, lastSlash + 1)}${fixBrandCasing(ref.slice(lastSlash + 1))}`;
}

function stableStringify(value: unknown): string {
    if (Array.isArray(value)) {
        return `[${value.map((item) => stableStringify(item)).join(",")}]`;
    }

    if (value && typeof value === "object") {
        const entries = Object.entries(value as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b));
        return `{${entries.map(([key, entryValue]) => `${JSON.stringify(key)}:${stableStringify(entryValue)}`).join(",")}}`;
    }

    return JSON.stringify(value) ?? "undefined";
}

function renameBrandDefinitionKeys(defs: Record<string, unknown>): void {
    for (const oldKey of Object.keys(defs)) {
        const newKey = fixBrandCasing(oldKey);
        if (newKey === oldKey) continue;
        if (newKey in defs && stableStringify(defs[newKey]) !== stableStringify(defs[oldKey])) {
            throw new Error(
                `Brand-casing normalization collision: "${oldKey}" -> "${newKey}" but a different definition already exists under "${newKey}".`
            );
        }
        defs[newKey] = defs[oldKey];
        delete defs[oldKey];
    }
}

function toPascalCase(name: string): string {
    return fixBrandCasing(name.split(/[-_.]/).map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join(""));
}

function toJavaClassName(typeName: string): string {
    return fixBrandCasing(typeName.split(/[._]/).map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join(""));
}

/** Java reserved keywords and Object method names that cannot be used as record component names. */
const JAVA_RESERVED_IDENTIFIERS = new Set([
    "abstract", "assert", "boolean", "break", "byte", "case", "catch", "char", "class", "const",
    "continue", "default", "do", "double", "else", "enum", "extends", "final", "finally", "float",
    "for", "goto", "if", "implements", "import", "instanceof", "int", "interface", "long", "native",
    "new", "package", "private", "protected", "public", "return", "short", "static", "strictfp",
    "super", "switch", "synchronized", "this", "throw", "throws", "transient", "try", "void",
    "volatile", "while",
    // Object methods that conflict with record component accessor names
    "wait", "notify", "notifyAll", "getClass", "clone", "finalize", "toString", "hashCode", "equals",
]);

function toCamelCase(name: string): string {
    const pascal = toPascalCase(name);
    let result = pascal.charAt(0).toLowerCase() + pascal.slice(1);
    if (JAVA_RESERVED_IDENTIFIERS.has(result)) {
        result = result + "_";
    }
    return result;
}

function toEnumConstant(value: string): string {
    const constant = value.toUpperCase().replace(/[^A-Z0-9]/g, "_").replace(/^_+/, "").replace(/_+/g, "_");
    if (constant.length === 0) return "_";
    return /^[0-9]/.test(constant) ? `_${constant}` : constant;
}

// ── Schema path resolution ───────────────────────────────────────────────────

/** Resolve a JSON schema staged from the pinned GitHub Release artifact. */
async function resolveCopilotSchemaPath(fileName: string): Promise<string> {
    const schemaPath = path.join(
        process.env.COPILOT_CLI_SCHEMA_OUTPUT ?? path.join(REPO_ROOT, "scripts/codegen/target/schemas"),
        fileName,
    );
    try {
        await fs.access(schemaPath);
        return schemaPath;
    } catch {
        throw new Error(`${fileName} not found. Run 'npm run fetch:schemas' in java/scripts/codegen.`);
    }
}

async function getSessionEventsSchemaPath(): Promise<string> {
    return resolveCopilotSchemaPath("session-events.schema.json");
}

async function getApiSchemaPath(): Promise<string> {
    return resolveCopilotSchemaPath("api.schema.json");
}

// ── File writing ─────────────────────────────────────────────────────────────

let pendingOutput: Map<string, string> | undefined;

async function writeGeneratedFile(relativePath: string, content: string): Promise<string> {
    const fullPath = path.join(OUTPUT_ROOT, relativePath);
    const files = rpcGeneration?.files ?? pendingOutput;
    if (files) {
        const previous = files.get(relativePath);
        if (rpcGeneration?.variantNames && previous !== undefined && previous !== content) {
            throw new Error(`Conflicting Java RPC output "${relativePath}".`);
        }
        files.set(relativePath, content);
        return fullPath;
    }
    await fs.mkdir(path.dirname(fullPath), { recursive: true });
    await fs.writeFile(fullPath, content, "utf-8");
    console.log(`  ✓ ${relativePath}`);
    return fullPath;
}

// ── Java type mapping ─────────────────────────────────────────────────────────

interface JavaTypeResult {
    javaType: string;
    imports: Set<string>;
}

// Module-level state for $ref resolution during codegen.
// Set before each schema generation pass; used by schemaTypeToJava and helpers.
let currentDefinitions: Record<string, JSONSchema7> = {};
const pendingStandaloneTypes = new Map<string, JSONSchema7>();
const promotedNestedUnionTypes = new Set<string>();
const promotedSealedUnionTypes = new Set<string>();
const generatedSessionEventTypeNames = new Set<string>();

// Cross-schema definitions: keyed by schema filename (e.g. "session-events.schema.json"),
// value is the definitions map from that schema. Populated by generateRpcTypes so that
// cross-schema $ref values like "session-events.schema.json#/definitions/Foo" can be resolved.
const crossSchemaDefinitions = new Map<string, Record<string, JSONSchema7>>();

/**
 * Resolve a $ref in a JSON Schema against the current definitions.
 * Returns the resolved schema, or the original if no $ref is present.
 */
function resolveRef(schema: JSONSchema7 | undefined): JSONSchema7 | undefined {
    if (!schema) return schema;
    if (schema.$ref) {
        const name = schema.$ref.replace(/^#\/definitions\//, "");
        const resolved = currentDefinitions[name];
        if (!resolved) {
            console.warn(`[codegen] Unresolved $ref: ${schema.$ref}`);
            return schema;
        }
        return resolved;
    }
    return schema;
}

function hasOmissionSentinel(schema: JSONSchema7): boolean {
    return (schema.anyOf ?? []).some(
        (variant) =>
            typeof variant === "object"
            && variant !== null
            && typeof (variant as JSONSchema7).not === "object"
            && (variant as JSONSchema7).not !== null
            && Object.keys((variant as JSONSchema7).not as object).length === 0
    );
}

/**
 * Resolve a method's params schema to the object schema that carries its properties.
 *
 * Methods whose params object is entirely optional are published as
 * `anyOf: [{ not: {} }, { ...object }]`, so the properties live on a variant
 * rather than on the schema itself.
 */
function resolveMethodParamsSchema(method: RpcMethodNode): JSONSchema7 | undefined {
    const params = resolveRef(method.params ?? undefined);
    if (!params || typeof params !== "object") return undefined;
    if (params.properties) return params;
    if (!Array.isArray(params.anyOf)) return undefined;
    const objectVariants = resolveAnyOfVariants(params.anyOf as JSONSchema7[]).filter((variant) => !!variant.properties);
    return hasOmissionSentinel(params) && objectVariants.length === 1 ? objectVariants[0] : undefined;
}

function resolveMethodParamsUnionSchema(method: RpcMethodNode): JSONSchema7 | undefined {
    const params = resolveRef(method.params ?? undefined);
    if (!params || typeof params !== "object" || !Array.isArray(params.anyOf)) return undefined;
    const variants = resolveAnyOfVariants(params.anyOf as JSONSchema7[]);
    return variants.length > 1 && findDiscriminator(variants) ? params : undefined;
}

/** Extract the definition name from a $ref string (e.g., "#/definitions/Foo" → "Foo") */
function extractRefName(schema: JSONSchema7 | null | undefined): string | null {
    if (!schema?.$ref) return null;
    // Handle cross-schema refs
    const crossMatch = schema.$ref.match(/^[^#]+#\/definitions\/(.+)$/);
    if (crossMatch) return crossMatch[1];
    return schema.$ref.replace(/^#\/definitions\//, "");
}

function nullableResultReference(schema: JSONSchema7): JSONSchema7 | undefined {
    if (schema.anyOf?.length !== 2) return undefined;
    const [first, second] = schema.anyOf;
    if (typeof first !== "object" || typeof second !== "object") return undefined;
    if (first.type === "null" && second.$ref) return second;
    if (second.type === "null" && first.$ref) return first;
    return undefined;
}

/**
 * Whether an RPC method's result schema permits `null`. Java has no nullable
 * reference types, so the wrapper returns the non-null branch and the
 * generated Javadoc must disclose the absent case instead.
 */
function methodResultAllowsNull(method: RpcMethodNode): boolean {
    const original = method.result as JSONSchema7 | null | undefined;
    if (!original || typeof original !== "object") return false;
    const refName = extractRefName(original);
    const resolved = refName ? currentDefinitions[refName] : original;
    if (!resolved || typeof resolved !== "object") return false;
    return !!nullableResultReference(resolved);
}

// ── Discriminated union support ─────────────────────────────────────────────

interface DiscriminatorInfo {
    property: string;
    mapping: Map<string, { value: unknown; schema: JSONSchema7 }>;
}

function unionVariants(schema: JSONSchema7): JSONSchema7[] | undefined {
    const variants = schema.anyOf ?? schema.oneOf;
    return Array.isArray(variants) ? variants as JSONSchema7[] : undefined;
}

/**
 * Find a discriminator property shared by all variants in an anyOf.
 * A discriminator is a property with a `const` value that uniquely identifies each variant.
 */
function findDiscriminator(variants: JSONSchema7[]): DiscriminatorInfo | null {
    if (variants.length === 0) return null;
    const firstVariant = variants[0];
    if (!firstVariant.properties) return null;

    for (const [propName, propSchema] of Object.entries(firstVariant.properties).sort(([a], [b]) => a.localeCompare(b))) {
        if (typeof propSchema !== "object") continue;
        const schema = propSchema as JSONSchema7;
        if (schema.const === undefined) continue;

        const mapping = new Map<string, { value: unknown; schema: JSONSchema7 }>();
        let isValidDiscriminator = true;

        for (const variant of variants) {
            if (!variant.properties) { isValidDiscriminator = false; break; }
            const variantProp = variant.properties[propName];
            if (typeof variantProp !== "object") { isValidDiscriminator = false; break; }
            const variantSchema = variantProp as JSONSchema7;
            if (variantSchema.const === undefined) { isValidDiscriminator = false; break; }
            const key = String(variantSchema.const);
            if (mapping.has(key)) { isValidDiscriminator = false; break; }
            mapping.set(key, { value: variantSchema.const, schema: variant });
        }

        if (isValidDiscriminator && mapping.size === variants.length) {
            return { property: propName, mapping };
        }
    }
    return null;
}

/**
 * Resolve anyOf variants, handling $ref to definitions.
 */
function resolveAnyOfVariants(
    anyOf: JSONSchema7[],
    definitions: Record<string, JSONSchema7> = currentDefinitions
): JSONSchema7[] {
    return anyOf
        .map((v) => {
            if (v.$ref) {
                const name = v.$ref.replace(/^#\/definitions\//, "");
                return definitions[name] ?? v;
            }
            return v;
        })
        .filter((v) => v.type !== "null");
}

function findRequiredStringDiscriminator(
    variants: JSONSchema7[],
): DiscriminatorInfo | null {
    if (variants.length === 0) return null;
    const firstVariant = variants[0];
    if (!firstVariant.properties) return null;

    for (const [propName, propSchema] of Object.entries(firstVariant.properties).sort(([a], [b]) => a.localeCompare(b))) {
        if (typeof propSchema !== "object") continue;
        const schema = propSchema as JSONSchema7;
        if (typeof schema.const !== "string") continue;

        const mapping = new Map<string, { value: unknown; schema: JSONSchema7 }>();
        let isValidDiscriminator = true;

        for (const variant of variants) {
            if (!variant.properties || !variant.required?.includes(propName)) { isValidDiscriminator = false; break; }
            const variantProp = variant.properties[propName];
            if (typeof variantProp !== "object") { isValidDiscriminator = false; break; }
            const variantSchema = variantProp as JSONSchema7;
            if (typeof variantSchema.const !== "string") { isValidDiscriminator = false; break; }
            const key = variantSchema.const;
            if (mapping.has(key)) { isValidDiscriminator = false; break; }
            mapping.set(key, { value: variantSchema.const, schema: variant });
        }

        if (isValidDiscriminator && mapping.size === variants.length) {
            return { property: propName, mapping };
        }
    }
    return null;
}

function resolveUnionVariants(
    schema: JSONSchema7,
    definitions: Record<string, JSONSchema7> = currentDefinitions
): JSONSchema7[] | null {
    const variants = unionVariants(schema);
    if (!variants) return null;
    return resolveAnyOfVariants(variants, definitions);
}

function isSealedStandaloneUnionCandidate(
    schema: JSONSchema7,
    definitions: Record<string, JSONSchema7> = currentDefinitions
): boolean {
    const variants = resolveUnionVariants(schema, definitions);
    return !!variants
        && variants.length > 1
        && !!findRequiredStringDiscriminator(variants)
        && variants.every((variant) => variant.type === "object" && variant.additionalProperties === false);
}

function referencedDefinitionName(schema: JSONSchema7 | boolean | undefined): string | null {
    if (!schema || typeof schema !== "object" || !schema.$ref?.startsWith("#/definitions/")) return null;
    return schema.$ref.slice("#/definitions/".length);
}

function discriminatedUnionReferencesInVariants(
    typeName: string,
    definitions: Record<string, JSONSchema7>
): string[] {
    const schema = definitions[typeName];
    const variants = schema ? resolveUnionVariants(schema, definitions) : null;
    if (!variants) return [];

    const refs = new Set<string>();
    for (const variant of variants) {
        for (const property of Object.values(variant.properties ?? {})) {
            if (!property || typeof property !== "object") continue;
            const propertySchema = property as JSONSchema7;
            const directName = referencedDefinitionName(propertySchema);
            if (directName && isSealedStandaloneUnionCandidate(definitions[directName], definitions) && !hasHistoricalRpcVariantOwner(directName, definitions)) {
                refs.add(directName);
            }
            if (propertySchema.type === "array" && propertySchema.items && !Array.isArray(propertySchema.items)) {
                const itemName = referencedDefinitionName(propertySchema.items as JSONSchema7);
                if (itemName && isSealedStandaloneUnionCandidate(definitions[itemName], definitions) && !hasHistoricalRpcVariantOwner(itemName, definitions)) {
                    refs.add(itemName);
                }
            }
        }
    }
    return [...refs].sort();
}

function hasHistoricalRpcVariantOwner(
    typeName: string,
    definitions: Record<string, JSONSchema7>
): boolean {
    const variants = resolveUnionVariants(definitions[typeName], definitions);
    if (!variants) return false;
    return variants.some((variant) => {
        const discriminator = findRequiredStringDiscriminator(variants);
        if (!discriminator) return false;
        for (const [discValue, { schema: variantSchema }] of discriminator.mapping) {
            if (variantSchema !== variant) continue;
            const variantClassName = (variantSchema as JSONSchema7 & { title?: string }).title ?? `${typeName}${toPascalCase(discValue)}`;
            return Object.hasOwn(RPC_VARIANT_OWNERS, variantClassName);
        }
        return false;
    });
}

function collectSealedStandaloneUnionTypeNames(
    definitions: Record<string, JSONSchema7>,
    excludedSeeds: ReadonlySet<string> = new Set()
): Set<string> {
    const seeds = new Map<string, string[]>();
    const referencedBySeed = new Set<string>();
    for (const [typeName, schema] of Object.entries(definitions)) {
        if (excludedSeeds.has(typeName)) continue;
        if (!isSealedStandaloneUnionCandidate(schema, definitions)) continue;
        if (hasHistoricalRpcVariantOwner(typeName, definitions)) continue;
        const references = discriminatedUnionReferencesInVariants(typeName, definitions);
        if (references.length === 0) continue;
        seeds.set(typeName, references);
        for (const reference of references) referencedBySeed.add(reference);
    }

    const promoted = new Set<string>();
    for (const [typeName, references] of seeds) {
        if (referencedBySeed.has(typeName)) continue;
        promoted.add(typeName);
        for (const reference of references) promoted.add(reference);
    }
    return promoted;
}

function collectDirectMethodRefNames(schema: RpcSchema): Set<string> {
    const refs = new Set<string>();
    const visit = (node: unknown): void => {
        if (!node || typeof node !== "object") return;
        const objectNode = node as Record<string, unknown>;
        if (typeof objectNode.rpcMethod === "string") {
            for (const key of ["params", "result"]) {
                const ref = referencedDefinitionName(objectNode[key] as JSONSchema7);
                if (ref) refs.add(ref);
            }
            return;
        }
        for (const value of Object.values(objectNode)) visit(value);
    };
    for (const section of [schema.server, schema.session, schema.clientSession, schema.clientGlobal]) {
        visit(section);
    }
    return refs;
}

function collectImmediateObjectUnionRefs(
    rootNames: ReadonlySet<string>,
    definitions: Record<string, JSONSchema7>
): Set<string> {
    const refs = new Set<string>();
    for (const rootName of rootNames) {
        const root = definitions[rootName];
        collectImmediateObjectUnionRefsFromSchema(root, definitions, refs);
    }
    return refs;
}

function collectImmediateObjectUnionRefsFromSchema(
    schema: JSONSchema7 | undefined,
    definitions: Record<string, JSONSchema7>,
    refs: Set<string>
): void {
    if (!schema || schema.type !== "object" || !schema.properties) return;
    for (const property of Object.values(schema.properties)) {
        if (!property || typeof property !== "object") continue;
        const propertySchema = property as JSONSchema7;
        const directName = referencedDefinitionName(propertySchema);
        if (directName && isSealedStandaloneUnionCandidate(definitions[directName], definitions)) {
            refs.add(directName);
        }
        if (propertySchema.type === "array" && propertySchema.items && !Array.isArray(propertySchema.items)) {
            const itemName = referencedDefinitionName(propertySchema.items as JSONSchema7);
            if (itemName && isSealedStandaloneUnionCandidate(definitions[itemName], definitions)) {
                refs.add(itemName);
            }
        }
    }
}

function collectImmediateMethodObjectUnionRefs(
    schema: RpcSchema,
    definitions: Record<string, JSONSchema7>
): Set<string> {
    const refs = new Set<string>();
    const visit = (node: unknown): void => {
        if (!node || typeof node !== "object") return;
        const objectNode = node as Record<string, unknown>;
        if (typeof objectNode.rpcMethod === "string") {
            for (const key of ["params", "result"]) {
                const methodSchema = objectNode[key] as JSONSchema7 | null | undefined;
                const ref = referencedDefinitionName(methodSchema ?? undefined);
                collectImmediateObjectUnionRefsFromSchema(ref ? definitions[ref] : methodSchema ?? undefined, definitions, refs);
            }
            return;
        }
        for (const value of Object.values(objectNode)) visit(value);
    };
    for (const section of [schema.server, schema.session, schema.clientSession, schema.clientGlobal]) {
        visit(section);
    }
    return refs;
}

export function collectNestedDiscriminatedUnionTypeNames(
    root: unknown,
    definitions: Record<string, JSONSchema7>
): Set<string> {
    const promotedTypes = new Set<string>();
    const definitionName = (schema: JSONSchema7): string | null => {
        return schema.$ref?.match(/^#\/definitions\/([^/]+)$/)?.[1] ?? null;
    };
    const resolveLocal = (schema: JSONSchema7): JSONSchema7 | null => {
        const name = definitionName(schema);
        return name ? definitions[name] ?? null : schema;
    };
    const closedDiscriminatedUnionVariants = (schema: JSONSchema7): JSONSchema7[] | null => {
        const resolved = resolveLocal(schema);
        const members = resolved ? unionVariants(resolved) : undefined;
        if (!members) return null;
        const variants = resolveAnyOfVariants(members, definitions);
        return variants.length > 1
            && findDiscriminator(variants)
            && variants.every((variant) => variant.additionalProperties === false)
            ? variants
            : null;
    };

    const rootSchema = typeof root === "object" && root !== null ? root as JSONSchema7 : null;
    const rootVariants = rootSchema ? closedDiscriminatedUnionVariants(rootSchema) : null;
    if (!rootVariants) return promotedTypes;

    const nestedUnionItems: JSONSchema7[] = [];
    for (const variant of rootVariants) {
        for (const property of Object.values(variant.properties ?? {})) {
            if (!property || typeof property !== "object") continue;
            const propertySchema = resolveLocal(property as JSONSchema7);
            if (
                propertySchema?.type === "array"
                && propertySchema.items
                && !Array.isArray(propertySchema.items)
                && closedDiscriminatedUnionVariants(propertySchema.items as JSONSchema7)
            ) {
                nestedUnionItems.push(propertySchema.items as JSONSchema7);
            }
        }
    }

    const visitedDefinitions = new Set<string>();
    const visit = (schema: JSONSchema7): void => {
        const name = definitionName(schema);
        if (name) {
            if (visitedDefinitions.has(name)) return;
            visitedDefinitions.add(name);
            const resolved = definitions[name];
            if (!resolved) return;
            if (closedDiscriminatedUnionVariants(schema)) {
                promotedTypes.add(name);
            }
            visit(resolved);
            return;
        }

        for (const property of Object.values(schema.properties ?? {})) {
            if (property && typeof property === "object") {
                visit(property as JSONSchema7);
            }
        }
        if (schema.items && !Array.isArray(schema.items)) {
            visit(schema.items as JSONSchema7);
        }
        if (schema.additionalProperties && typeof schema.additionalProperties === "object") {
            visit(schema.additionalProperties as JSONSchema7);
        }
        for (const branch of [...(schema.anyOf ?? []), ...(schema.allOf ?? [])]) {
            if (branch && typeof branch === "object") {
                visit(branch as JSONSchema7);
            }
        }
    };

    for (const items of nestedUnionItems) visit(items);
    return promotedTypes;
}

/**
 * Generate a polymorphic base class and variant subclasses for a discriminated union result type.
 */
interface RpcVariant {
    discriminatorValue: string;
    variantClassName: string;
    schema: JSONSchema7;
}

interface RpcUnion {
    schema: JSONSchema7;
    packageName: string;
    packageDir: string;
    discriminatorProperty: string;
    variants: RpcVariant[];
}

interface RpcGeneration {
    files: Map<string, string>;
    unions: Map<string, RpcUnion>;
    variantNames?: Map<string, Map<string, string>>;
}

let rpcGeneration: RpcGeneration | undefined;

function planRpcVariantNames(
    generation: RpcGeneration,
    historicalOwners: Readonly<Record<string, string>>
): Map<string, Map<string, string>> {
    const memberships = new Map<string, Map<string, RpcVariant>>();
    const reserved = new Set([...generation.files.keys()].map((file) => path.basename(file, ".java")));
    for (const [root, union] of generation.unions) {
        if (reserved.has(root)) throw new Error(`Conflicting Java RPC union name "${root}".`);
        reserved.add(root);
        for (const variant of union.variants) {
            const owners = memberships.get(variant.variantClassName) ?? new Map<string, RpcVariant>();
            for (const [otherRoot, other] of owners) {
                if (stableStringify(other.schema) !== stableStringify(variant.schema) ||
                    generation.unions.get(otherRoot)?.discriminatorProperty !== union.discriminatorProperty ||
                    other.discriminatorValue !== variant.discriminatorValue) {
                    throw new Error(`Incompatible schemas for Java RPC variant "${variant.variantClassName}" in "${otherRoot}" and "${root}".`);
                }
            }
            owners.set(root, variant);
            memberships.set(variant.variantClassName, owners);
        }
    }
    for (const [name, owner] of Object.entries(historicalOwners)) {
        if (!memberships.get(name)?.has(owner)) {
            throw new Error(`Missing historical Java RPC owner "${owner}" for "${name}".`);
        }
    }
    for (const name of memberships.keys()) {
        if (reserved.has(name)) throw new Error(`Conflicting Java RPC variant name "${name}".`);
        reserved.add(name);
    }
    const result = new Map<string, Map<string, string>>();
    for (const [name, owners] of [...memberships].sort(([a], [b]) => a.localeCompare(b))) {
        const roots = [...owners.keys()].sort();
        const canonicalOwner = Object.hasOwn(historicalOwners, name) ? historicalOwners[name] : roots[0];
        if (!Object.hasOwn(historicalOwners, name) && roots.length > 1) {
            throw new Error(`Ambiguous Java RPC owner for "${name}": ${roots.join(", ")}. Record its historical owner explicitly.`);
        }
        for (const root of roots) {
            const contextualName = root === canonicalOwner ? name : `${root}${name}`;
            if (root !== canonicalOwner) {
                if (reserved.has(contextualName)) throw new Error(`Conflicting Java RPC contextual name "${contextualName}".`);
                reserved.add(contextualName);
            }
            const names = result.get(root) ?? new Map<string, string>();
            names.set(name, contextualName);
            result.set(root, names);
        }
    }
    return result;
}

async function generatePolymorphicResultClass(
    className: string,
    schema: JSONSchema7,
    packageName: string,
    packageDir: string
): Promise<void> {
    const variants = resolveAnyOfVariants(unionVariants(schema) ?? []);
    const discriminator = findDiscriminator(variants);
    const experimental = isSchemaExperimental(schema);

    if (!discriminator) {
        console.warn(`[codegen] Cannot find discriminator for ${className} — skipping polymorphic generation`);
        return;
    }

    const variantInfos: RpcVariant[] = [];
    for (const [discValue, { schema: variantSchema }] of discriminator.mapping) {
        const variantClassName = (variantSchema as JSONSchema7 & { title?: string }).title ?? `${className}${toPascalCase(discValue)}`;
        variantInfos.push({ discriminatorValue: discValue, variantClassName, schema: variantSchema });
    }

    if (rpcGeneration && !rpcGeneration.variantNames) {
        const previous = rpcGeneration.unions.get(className);
        if (previous && stableStringify(previous.schema) !== stableStringify(schema)) {
            throw new Error(`Conflicting Java RPC union "${className}".`);
        }
        rpcGeneration.unions.set(className, {
            schema, packageName, packageDir, discriminatorProperty: discriminator.property, variants: variantInfos,
        });
        // Resolve fields now so nested/standalone unions participate in the same
        // ownership plan. Nothing is written until every membership is known.
        for (const variant of variantInfos) {
            await generatePolymorphicVariantClass(variant.variantClassName, variant.schema, variant.discriminatorValue, discriminator.property, className, packageName, packageDir);
        }
        return;
    }
    if (rpcGeneration?.variantNames) {
        for (const variant of variantInfos) {
            const name = rpcGeneration.variantNames.get(className)?.get(variant.variantClassName);
            if (!name) throw new Error(`Unplanned Java RPC variant "${variant.variantClassName}" in "${className}".`);
            variant.variantClassName = name;
        }
    }

    // Generate the abstract base class
    const baseLines: string[] = [];
    baseLines.push(COPYRIGHT);
    baseLines.push("");
    baseLines.push(AUTO_GENERATED_HEADER);
    baseLines.push(GENERATED_FROM_API);
    baseLines.push("");
    baseLines.push(`package ${packageName};`);
    baseLines.push("");
    baseLines.push(`import com.fasterxml.jackson.annotation.JsonIgnoreProperties;`);
    baseLines.push(`import com.fasterxml.jackson.annotation.JsonSubTypes;`);
    baseLines.push(`import com.fasterxml.jackson.annotation.JsonTypeInfo;`);
    if (experimental) {
        baseLines.push(`import com.github.copilot.CopilotExperimental;`);
    }
    baseLines.push(`import javax.annotation.processing.Generated;`);
    baseLines.push("");
    if (schema.description || experimental) {
        baseLines.push(`/**`);
        baseLines.push(` * ${schema.description ?? `Polymorphic result type {@code ${className}}.`}`);
        appendExperimentalTypeApiNote(baseLines, schema);
        baseLines.push(` *`);
        baseLines.push(` * @since 1.0.0`);
        baseLines.push(` */`);
    }
    const typeInfoInclude = promotedNestedUnionTypes.has(className)
        ? `, include = JsonTypeInfo.As.EXISTING_PROPERTY`
        : "";
    baseLines.push(`@JsonTypeInfo(use = JsonTypeInfo.Id.NAME${typeInfoInclude}, property = "${discriminator.property}", visible = true)`);
    baseLines.push(`@JsonSubTypes({`);
    for (let i = 0; i < variantInfos.length; i++) {
        const v = variantInfos[i];
        const comma = i < variantInfos.length - 1 ? "," : "";
        baseLines.push(`    @JsonSubTypes.Type(value = ${v.variantClassName}.class, name = "${v.discriminatorValue}")${comma}`);
    }
    baseLines.push(`})`);
    if (experimental) {
        baseLines.push(`@CopilotExperimental`);
    }
    baseLines.push(`@JsonIgnoreProperties(ignoreUnknown = true)`);
    baseLines.push(GENERATED_ANNOTATION);
    baseLines.push(`public abstract class ${className} {`);
    baseLines.push("");
    baseLines.push(`    /**`);
    baseLines.push(`     * Returns the discriminator value for this variant.`);
    baseLines.push(`     *`);
    baseLines.push(`     * @return the ${discriminator.property} discriminator`);
    baseLines.push(`     */`);
    baseLines.push(`    public abstract String get${toPascalCase(discriminator.property)}();`);
    baseLines.push(`}`);
    baseLines.push("");

    await writeGeneratedFile(`${packageDir}/${className}.java`, baseLines.join("\n"));

    // Generate each variant subclass
    for (const variant of variantInfos) {
        await generatePolymorphicVariantClass(variant.variantClassName, variant.schema, variant.discriminatorValue, discriminator.property, className, packageName, packageDir);
    }
}

/**
 * Generate a single variant subclass of a polymorphic result type.
 */
async function generatePolymorphicVariantClass(
    className: string,
    schema: JSONSchema7,
    discriminatorValue: string,
    discriminatorProperty: string,
    baseClassName: string,
    packageName: string,
    packageDir: string
): Promise<void> {
    const experimental = isSchemaExperimental(schema);
    const allImports = new Set<string>([
        "com.fasterxml.jackson.annotation.JsonIgnoreProperties",
        "com.fasterxml.jackson.annotation.JsonInclude",
        "com.fasterxml.jackson.annotation.JsonProperty",
        "javax.annotation.processing.Generated",
    ]);
    if (experimental) {
        allImports.add("com.github.copilot.CopilotExperimental");
    }
    const nestedTypes = new Map<string, JavaClassDef>();

    // Collect fields (excluding the discriminator property)
    interface FieldInfo {
        jsonName: string;
        javaName: string;
        javaType: string;
        description?: string;
    }

    const fields: FieldInfo[] = [];
    if (schema.properties) {
        for (const [propName, propSchema] of Object.entries(schema.properties)) {
            if (propName === discriminatorProperty) continue;
            if (typeof propSchema !== "object") continue;
            const prop = propSchema as JSONSchema7;
            const result = schemaTypeToJava(prop, false, className, propName, nestedTypes);
            for (const imp of result.imports) allImports.add(imp);
            fields.push({
                jsonName: propName,
                javaName: toCamelCase(propName),
                javaType: result.javaType,
                description: prop.description,
            });
        }
    }

    const lines: string[] = [];
    lines.push(COPYRIGHT);
    lines.push("");
    lines.push(AUTO_GENERATED_HEADER);
    lines.push(GENERATED_FROM_API);
    lines.push("");
    lines.push(`package ${packageName};`);
    lines.push("");

    // Placeholder for imports
    const importPlaceholderIdx = lines.length;
    lines.push("__IMPORTS__");
    lines.push("");

    if (schema.description) {
        lines.push(`/**`);
        lines.push(` * ${schema.description}`);
        appendExperimentalTypeApiNote(lines, schema);
        lines.push(` *`);
        lines.push(` * @since 1.0.0`);
        lines.push(` */`);
    } else {
        lines.push(`/**`);
        lines.push(` * Variant {@code ${discriminatorValue}} of {@link ${baseClassName}}.`);
        appendExperimentalTypeApiNote(lines, schema);
        lines.push(` *`);
        lines.push(` * @since 1.0.0`);
        lines.push(` */`);
    }
    if (experimental) {
        lines.push(`@CopilotExperimental`);
    }
    lines.push(`@JsonIgnoreProperties(ignoreUnknown = true)`);
    lines.push(`@JsonInclude(JsonInclude.Include.NON_NULL)`);
    lines.push(GENERATED_ANNOTATION);
    lines.push(`public final class ${className} extends ${baseClassName} {`);
    lines.push("");

    // Discriminator field
    lines.push(`    @JsonProperty("${discriminatorProperty}")`);
    lines.push(`    private final String ${toCamelCase(discriminatorProperty)} = "${discriminatorValue}";`);
    lines.push("");
    lines.push(`    @Override`);
    lines.push(`    public String get${toPascalCase(discriminatorProperty)}() { return ${toCamelCase(discriminatorProperty)}; }`);
    lines.push("");

    // Other fields
    for (const field of fields) {
        if (field.description) {
            lines.push(`    /** ${field.description} */`);
        }
        lines.push(`    @JsonProperty("${field.jsonName}")`);
        lines.push(`    private ${field.javaType} ${field.javaName};`);
        lines.push("");
    }

    // Getters and setters
    for (const field of fields) {
        lines.push(`    public ${field.javaType} get${field.javaName.charAt(0).toUpperCase() + field.javaName.slice(1)}() { return ${field.javaName}; }`);
        lines.push(`    public void set${field.javaName.charAt(0).toUpperCase() + field.javaName.slice(1)}(${field.javaType} ${field.javaName}) { this.${field.javaName} = ${field.javaName}; }`);
        lines.push("");
    }

    // Render nested types
    for (const [, nested] of nestedTypes) {
        lines.push(...renderNestedType(nested, 1, new Map(), allImports));
    }

    if (lines[lines.length - 1] === "") lines.pop();
    lines.push(`}`);
    lines.push("");

    // Replace import placeholder
    const sortedImports = [...allImports].sort();
    const importLines = sortedImports.map((i) => `import ${i};`).join("\n");
    lines[importPlaceholderIdx] = importLines;

    if (rpcGeneration && !rpcGeneration.variantNames) return;
    await writeGeneratedFile(`${packageDir}/${className}.java`, lines.join("\n"));
}

async function generateSealedUnionInterface(
    className: string,
    schema: JSONSchema7,
    packageName: string,
    packageDir: string,
    headerComment: string
): Promise<void> {
    const variants = resolveUnionVariants(schema);
    const discriminator = variants ? findRequiredStringDiscriminator(variants) : null;
    const experimental = isSchemaExperimental(schema);

    if (!variants || !discriminator) {
        console.warn(`[codegen] Cannot find required string discriminator for ${className} — skipping sealed union generation`);
        return;
    }

    const variantInfos: RpcVariant[] = [];
    for (const [discValue, { schema: variantSchema }] of discriminator.mapping) {
        const variantClassName = (variantSchema as JSONSchema7 & { title?: string }).title ?? `${className}${toPascalCase(discValue)}`;
        variantInfos.push({ discriminatorValue: discValue, variantClassName, schema: variantSchema });
    }

    const baseLines: string[] = [];
    baseLines.push(COPYRIGHT);
    baseLines.push("");
    baseLines.push(AUTO_GENERATED_HEADER);
    baseLines.push(headerComment);
    baseLines.push("");
    baseLines.push(`package ${packageName};`);
    baseLines.push("");
    baseLines.push(`import com.fasterxml.jackson.annotation.JsonIgnoreProperties;`);
    baseLines.push(`import com.fasterxml.jackson.annotation.JsonProperty;`);
    baseLines.push(`import com.fasterxml.jackson.annotation.JsonSubTypes;`);
    baseLines.push(`import com.fasterxml.jackson.annotation.JsonTypeInfo;`);
    if (experimental) {
        baseLines.push(`import com.github.copilot.CopilotExperimental;`);
    }
    baseLines.push(`import javax.annotation.processing.Generated;`);
    baseLines.push("");
    if (schema.description || experimental) {
        baseLines.push(`/**`);
        baseLines.push(` * ${schema.description ?? `Polymorphic type {@code ${className}}.`}`);
        appendExperimentalTypeApiNote(baseLines, schema);
        baseLines.push(` *`);
        baseLines.push(` * @since 1.0.0`);
        baseLines.push(` */`);
    }
    baseLines.push(`@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, include = JsonTypeInfo.As.EXISTING_PROPERTY, property = "${discriminator.property}", visible = true)`);
    baseLines.push(`@JsonSubTypes({`);
    for (let i = 0; i < variantInfos.length; i++) {
        const v = variantInfos[i];
        const comma = i < variantInfos.length - 1 ? "," : "";
        baseLines.push(`    @JsonSubTypes.Type(value = ${v.variantClassName}.class, name = "${v.discriminatorValue}")${comma}`);
    }
    baseLines.push(`})`);
    if (experimental) {
        baseLines.push(`@CopilotExperimental`);
    }
    baseLines.push(`@JsonIgnoreProperties(ignoreUnknown = true)`);
    baseLines.push(GENERATED_ANNOTATION);
    baseLines.push(`public sealed interface ${className} permits ${variantInfos.map((variant) => variant.variantClassName).join(", ")} {`);
    baseLines.push(`    /**`);
    baseLines.push(`     * Returns the discriminator value for this variant.`);
    baseLines.push(`     *`);
    baseLines.push(`     * @return the ${discriminator.property} discriminator`);
    baseLines.push(`     */`);
    baseLines.push(`    @JsonProperty("${discriminator.property}")`);
    baseLines.push(`    String ${toCamelCase(discriminator.property)}();`);
    baseLines.push(`}`);
    baseLines.push("");

    await writeGeneratedFile(`${packageDir}/${className}.java`, baseLines.join("\n"));

    for (const variant of variantInfos) {
        await generateSealedUnionVariantRecord(
            variant.variantClassName,
            variant.schema,
            variant.discriminatorValue,
            discriminator.property,
            className,
            packageName,
            packageDir,
            headerComment
        );
    }
}

async function generateSealedUnionVariantRecord(
    className: string,
    schema: JSONSchema7,
    discriminatorValue: string,
    discriminatorProperty: string,
    baseClassName: string,
    packageName: string,
    packageDir: string,
    headerComment: string
): Promise<void> {
    const experimental = isSchemaExperimental(schema);
    const allImports = new Set<string>([
        "com.fasterxml.jackson.annotation.JsonIgnoreProperties",
        "com.fasterxml.jackson.annotation.JsonInclude",
        "com.fasterxml.jackson.annotation.JsonProperty",
        "com.fasterxml.jackson.annotation.JsonTypeInfo",
        "javax.annotation.processing.Generated",
    ]);
    if (experimental) {
        allImports.add("com.github.copilot.CopilotExperimental");
    }
    const nestedTypes = new Map<string, JavaClassDef>();
    const fields: { jsonName: string; javaName: string; javaType: string; description?: string; discriminator: boolean }[] = [];

    for (const [propName, propSchema] of Object.entries(schema.properties ?? {})) {
        if (typeof propSchema !== "object") continue;
        const prop = propSchema as JSONSchema7;
        if (propName === discriminatorProperty) {
            fields.push({
                jsonName: propName,
                javaName: toCamelCase(propName),
                javaType: "String",
                description: prop.description,
                discriminator: true,
            });
            continue;
        }
        const result = schemaTypeToJava(prop, false, className, propName, nestedTypes);
        for (const imp of result.imports) allImports.add(imp);
        fields.push({
            jsonName: propName,
            javaName: toCamelCase(propName),
            javaType: result.javaType,
            description: prop.description,
            discriminator: false,
        });
    }

    const nestedLines: string[] = [];
    for (const [, nested] of nestedTypes) {
        nestedLines.push(...renderNestedType(nested, 1, new Map(), allImports));
    }

    const lines: string[] = [];
    lines.push(COPYRIGHT);
    lines.push("");
    lines.push(AUTO_GENERATED_HEADER);
    lines.push(headerComment);
    lines.push("");
    lines.push(`package ${packageName};`);
    lines.push("");

    for (const imp of [...allImports].sort()) {
        lines.push(`import ${imp};`);
    }
    lines.push("");

    if (schema.description || experimental) {
        lines.push(`/**`);
        lines.push(` * ${schema.description ?? `Variant {@code ${discriminatorValue}} of {@link ${baseClassName}}.`}`);
        appendExperimentalTypeApiNote(lines, schema);
        lines.push(` *`);
        lines.push(` * @since 1.0.0`);
        lines.push(` */`);
    } else {
        lines.push(`/**`);
        lines.push(` * Variant {@code ${discriminatorValue}} of {@link ${baseClassName}}.`);
        lines.push(` *`);
        lines.push(` * @since 1.0.0`);
        lines.push(` */`);
    }
    if (experimental) {
        lines.push(`@CopilotExperimental`);
    }
    lines.push(`@JsonIgnoreProperties(ignoreUnknown = true)`);
    lines.push(`@JsonInclude(JsonInclude.Include.NON_NULL)`);
    lines.push(`@JsonTypeInfo(use = JsonTypeInfo.Id.NONE)`);
    lines.push(GENERATED_ANNOTATION);
    lines.push(`public record ${className}(`);
    for (let i = 0; i < fields.length; i++) {
        const field = fields[i];
        const comma = i < fields.length - 1 ? "," : "";
        if (field.description) lines.push(`    /** ${field.description} */`);
        lines.push(`    @JsonProperty("${field.jsonName}") ${field.javaType} ${field.javaName}${comma}`);
    }
    lines.push(`) implements ${baseClassName} {`);
    lines.push(`    public ${className} {`);
    lines.push(`        ${toCamelCase(discriminatorProperty)} = "${discriminatorValue}";`);
    lines.push(`    }`);

    const nonDiscriminatorFields = fields.filter((field) => !field.discriminator);
    if (nonDiscriminatorFields.length !== fields.length) {
        lines.push("");
        if (nonDiscriminatorFields.length === 0) {
            lines.push(`    public ${className}() {`);
            lines.push(`        this("${discriminatorValue}");`);
        } else {
            lines.push(`    public ${className}(`);
            for (let i = 0; i < nonDiscriminatorFields.length; i++) {
                const field = nonDiscriminatorFields[i];
                const comma = i < nonDiscriminatorFields.length - 1 ? "," : "";
                lines.push(`        ${field.javaType} ${field.javaName}${comma}`);
            }
            lines.push(`    ) {`);
            lines.push(`        this(${fields.map((field) => field.discriminator ? `"${discriminatorValue}"` : field.javaName).join(", ")});`);
        }
        lines.push(`    }`);
    }

    lines.push(...nestedLines);
    if (lines[lines.length - 1] === "") lines.pop();
    lines.push(`}`);
    lines.push("");

    await writeGeneratedFile(`${packageDir}/${className}.java`, lines.join("\n"));
}

interface JavaTypeResolution {
    definitions: Record<string, JSONSchema7>;
    standaloneTypes: Map<string, JSONSchema7>;
    promotedUnionTypes: Set<string>;
}

export function schemaTypeToJava(
    schema: JSONSchema7,
    required: boolean,
    context: string,
    propName: string,
    nestedTypes: Map<string, JavaClassDef>,
    resolution: JavaTypeResolution = {
        definitions: currentDefinitions,
        standaloneTypes: pendingStandaloneTypes,
        promotedUnionTypes: promotedNestedUnionTypes,
    }
): JavaTypeResult {
    const imports = new Set<string>();

    // Resolve $ref first — register standalone types for generation
    if (schema.$ref) {
        // Handle cross-schema $ref (e.g. "session-events.schema.json#/definitions/Foo")
        const crossSchemaMatch = schema.$ref.match(/^([^#]+)#\/definitions\/(.+)$/);
        if (crossSchemaMatch) {
            const [, schemaFile, typeName] = crossSchemaMatch;
            const externalDefs = crossSchemaDefinitions.get(schemaFile);
            if (
                schemaFile === "session-events.schema.json"
                && externalDefs?.[typeName]
                && generatedSessionEventTypeNames.has(typeName)
            ) {
                imports.add(`com.github.copilot.generated.${typeName}`);
                return { javaType: typeName, imports };
            }
            return { javaType: "Object", imports };
        }

        const name = schema.$ref.replace(/^#\/definitions\//, "");
        const resolved = resolution.definitions[name];
        if (resolved) {
            const directUnion = unionVariants(resolved);
            if (directUnion && ["InstallationReview", "McpInstallationReview", "SkillInstallationReview"].includes(name)) {
                const variants = resolveAnyOfVariants(directUnion, resolution.definitions);
                if (variants.length > 1 && findDiscriminator(variants)) {
                    resolution.standaloneTypes.set(name, resolved);
                    return { javaType: name, imports };
                }
            }
            if (resolution.promotedUnionTypes.has(name)
                && promotedSealedUnionTypes.has(name)
                && isSealedStandaloneUnionCandidate(resolved, resolution.definitions)) {
                resolution.standaloneTypes.set(name, resolved);
                return { javaType: name, imports };
            }
            if (
                resolution.promotedUnionTypes.has(name)
                && unionVariants(resolved)
            ) {
                const variants = resolveAnyOfVariants(unionVariants(resolved) ?? [], resolution.definitions);
                if (variants.length > 1 && findDiscriminator(variants)) {
                    resolution.standaloneTypes.set(name, resolved);
                    return { javaType: name, imports };
                }
            }
            // Enum or object types → register for standalone generation, return ref name
            if ((resolved.type === "string" && resolved.enum) ||
                (resolved.type === "object" && resolved.properties)) {
                resolution.standaloneTypes.set(name, resolved);
                return { javaType: name, imports };
            }
            // Other types (primitives, arrays, maps, anyOf unions) → resolve and recurse
            return schemaTypeToJava(resolved, required, context, propName, nestedTypes, resolution);
        }
        // Unresolved $ref — return name as-is
        console.warn(`[codegen] Unresolved $ref: ${schema.$ref}`);
        return { javaType: name, imports };
    }

    if (schema.anyOf) {
        const hasNull = schema.anyOf.some((s) => typeof s === "object" && (s as JSONSchema7).type === "null");
        const nonNull = schema.anyOf.filter((s) => typeof s === "object" && (s as JSONSchema7).type !== "null");
        if (nonNull.length === 1) {
            const result = schemaTypeToJava(nonNull[0] as JSONSchema7, required && !hasNull,
                context, propName, nestedTypes, resolution);
            return result;
        }
        // Multi-branch anyOf: fall through to Object, matching the C# generator's
        // behavior.  Java has no union types, so Object is the correct erasure for
        // anyOf[string, object] and similar multi-variant schemas.
        console.warn(`[codegen] ${context}.${propName}: anyOf with ${nonNull.length} non-null branches — falling back to Object`);
        return { javaType: "Object", imports };
    }

    if (schema.type === "string") {
        if (schema.format === "uuid") {
            imports.add("java.util.UUID");
            return { javaType: "UUID", imports };
        }
        if (schema.format === "date-time") {
            imports.add("java.time.OffsetDateTime");
            return { javaType: "OffsetDateTime", imports };
        }
        if (schema.enum && Array.isArray(schema.enum)) {
            const enumName = `${context}${toPascalCase(propName)}`;
            nestedTypes.set(enumName, {
                kind: "enum",
                name: enumName,
                values: schema.enum as string[],
                description: schema.description,
            });
            return { javaType: enumName, imports };
        }
        return { javaType: "String", imports };
    }

    if (Array.isArray(schema.type)) {
        const nonNullTypes = schema.type.filter((t) => t !== "null");
        if (nonNullTypes.length === 1) {
            const baseSchema = { ...schema, type: nonNullTypes[0] };
            return schemaTypeToJava(baseSchema as JSONSchema7, required, context, propName,
                nestedTypes, resolution);
        }
    }

    if (schema.type === "integer") {
        // JSON Schema "integer" maps to Long (boxed — always used for records).
        // Use primitive long for required fields in mutable-bean contexts if needed.
        return { javaType: required ? "long" : "Long", imports };
    }

    if (schema.type === "number") {
        return { javaType: required ? "double" : "Double", imports };
    }

    if (schema.type === "boolean") {
        return { javaType: required ? "boolean" : "Boolean", imports };
    }

    if (schema.type === "array") {
        const items = schema.items as JSONSchema7 | undefined;
        if (items) {
            // Always pass required=false so primitives are boxed (List<Long>, not List<long>)
            const itemResult = schemaTypeToJava(items, false, context, propName + "Item",
                nestedTypes, resolution);
            imports.add("java.util.List");
            for (const imp of itemResult.imports) imports.add(imp);
            return { javaType: `List<${itemResult.javaType}>`, imports };
        }
        imports.add("java.util.List");
        console.warn(`[codegen] ${context}.${propName}: array without typed items — falling back to List<Object>`);
        return { javaType: "List<Object>", imports };
    }

    if (schema.type === "object") {
        if (schema.properties && Object.keys(schema.properties).length > 0) {
            const nestedName = `${context}${toPascalCase(propName)}`;
            if (!nestedTypes.has(nestedName)) {
                nestedTypes.set(nestedName, {
                    kind: "class",
                    name: nestedName,
                    schema,
                    description: schema.description,
                });
            }
            return { javaType: nestedName, imports };
        }
        if (schema.additionalProperties) {
            if (schema.additionalProperties === true) {
                imports.add("java.util.Map");
                return { javaType: "Map<String, Object>", imports };
            }
            const valueSchema = typeof schema.additionalProperties === "object"
                ? schema.additionalProperties as JSONSchema7
                : { type: "object" } as JSONSchema7;
            // Always pass required=false so primitives are boxed (Map<String, Long>, not Map<String, long>)
            const valueResult = schemaTypeToJava(valueSchema, false, context,
                propName + "Value", nestedTypes, resolution);
            imports.add("java.util.Map");
            for (const imp of valueResult.imports) imports.add(imp);
            return { javaType: `Map<String, ${valueResult.javaType}>`, imports };
        }
        imports.add("java.util.Map");
        console.warn(`[codegen] ${context}.${propName}: object without typed properties or additionalProperties — falling back to Map<String, Object>`);
        return { javaType: "Map<String, Object>", imports };
    }

    console.warn(`[codegen] ${context}.${propName}: unrecognized schema (type=${JSON.stringify(schema.type)}) — falling back to Object`);
    return { javaType: "Object", imports };
}

// ── Class definitions ─────────────────────────────────────────────────────────

interface JavaClassDef {
    kind: "class" | "enum";
    name: string;
    description?: string;
    schema?: JSONSchema7;
    values?: string[];  // for enum
}

// ── Session Events codegen ────────────────────────────────────────────────────

interface EventVariant {
    typeName: string;
    className: string;
    dataSchema: JSONSchema7 | null;
    description?: string;
    stability?: string;
    deprecated?: boolean;
}

function extractEventVariants(schema: JSONSchema7): EventVariant[] {
    const definitions = schema.definitions as Record<string, JSONSchema7>;
    const sessionEvent = definitions?.SessionEvent;
    if (!sessionEvent?.anyOf) throw new Error("Schema must have SessionEvent definition with anyOf");

    return (sessionEvent.anyOf as JSONSchema7[])
        .map((variant) => {
            // Resolve $ref if present (1.0.35+ schema uses $ref to named definitions)
            let resolved = variant;
            if (variant.$ref) {
                const refName = variant.$ref.replace(/^#\/definitions\//, "");
                resolved = definitions[refName];
                if (!resolved) throw new Error(`Unresolved $ref: ${variant.$ref}`);
            }
            const typeSchema = resolved.properties?.type as JSONSchema7;
            const typeName = typeSchema?.const as string;
            if (!typeName) throw new Error("Variant must have type.const");
            const baseName = toJavaClassName(typeName);
            let dataSchema = resolved.properties?.data as JSONSchema7 | undefined;
            // Resolve $ref on data schema if present
            if (dataSchema?.$ref) {
                const dataRefName = dataSchema.$ref.replace(/^#\/definitions\//, "");
                dataSchema = definitions[dataRefName];
            }
            return {
                typeName,
                className: `${baseName}Event`,
                dataSchema: dataSchema ?? null,
                description: resolved.description,
                stability: (variant as unknown as Record<string, unknown>).stability as string | undefined,
                deprecated: (variant as unknown as Record<string, unknown>).deprecated === true,
            };
        })
        .filter((v) => !EXCLUDED_EVENT_TYPES.has(v.typeName) && !isSchemaInternal(v.dataSchema));
}

async function generateSessionEvents(schemaPath: string): Promise<void> {
    console.log("\n📋 Generating session event classes...");
    const schemaContent = await fs.readFile(schemaPath, "utf-8");
    const schema = normalizeSchemaBrandCasing(JSON.parse(schemaContent) as JSONSchema7);

    // Set module-level definitions for $ref resolution
    currentDefinitions = (schema.definitions ?? {}) as Record<string, JSONSchema7>;
    pendingStandaloneTypes.clear();
    promotedSealedUnionTypes.clear();

    const variants = extractEventVariants(schema);
    const packageName = "com.github.copilot.generated";
    const packageDir = `sdk/src/generated/java/com/github/copilot/generated`;

    // Generate base SessionEvent class
    await generateSessionEventBaseClass(variants, packageName, packageDir);

    // Generate one class file per event variant
    for (const variant of variants) {
        await generateEventVariantClass(variant, packageName, packageDir);
    }

    // Generate standalone types discovered via $ref resolution
    await generatePendingStandaloneTypes(packageName, packageDir, GENERATED_FROM_SESSION_EVENTS);

    generatedSessionEventTypeNames.clear();
    if (pendingOutput) {
        for (const file of pendingOutput.keys()) {
            if (path.dirname(file) === packageDir && file.endsWith(".java")) {
                generatedSessionEventTypeNames.add(path.basename(file, ".java"));
            }
        }
    } else {
        for (const entry of await fs.readdir(path.join(OUTPUT_ROOT, packageDir), { withFileTypes: true })) {
            if (entry.isFile() && entry.name.endsWith(".java")) {
                generatedSessionEventTypeNames.add(path.basename(entry.name, ".java"));
            }
        }
    }

    console.log(`✅ Generated ${variants.length + 1} session event files`);
}

async function generateSessionEventBaseClass(
    variants: EventVariant[],
    packageName: string,
    packageDir: string
): Promise<void> {
    const lines: string[] = [];
    lines.push(COPYRIGHT);
    lines.push("");
    lines.push(AUTO_GENERATED_HEADER);
    lines.push(GENERATED_FROM_SESSION_EVENTS);
    lines.push("");
    lines.push(`package ${packageName};`);
    lines.push("");
    lines.push(`import com.fasterxml.jackson.annotation.JsonIgnoreProperties;`);
    lines.push(`import com.fasterxml.jackson.annotation.JsonInclude;`);
    lines.push(`import com.fasterxml.jackson.annotation.JsonProperty;`);
    lines.push(`import com.fasterxml.jackson.annotation.JsonSubTypes;`);
    lines.push(`import com.fasterxml.jackson.annotation.JsonTypeInfo;`);
    lines.push(`import java.time.OffsetDateTime;`);
    lines.push(`import java.util.UUID;`);
    lines.push(`import javax.annotation.processing.Generated;`);
    lines.push("");
    lines.push(`/**`);
    lines.push(` * Base class for all generated session events.`);
    lines.push(` *`);
    lines.push(` * @since 1.0.0`);
    lines.push(` */`);
    lines.push(`@JsonIgnoreProperties(ignoreUnknown = true)`);
    lines.push(`@JsonInclude(JsonInclude.Include.NON_NULL)`);
    lines.push(`@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = "type", visible = true, defaultImpl = UnknownSessionEvent.class)`);
    lines.push(`@JsonSubTypes({`);
    for (let i = 0; i < variants.length; i++) {
        const v = variants[i];
        const comma = i < variants.length - 1 ? "," : "";
        lines.push(`    @JsonSubTypes.Type(value = ${v.className}.class, name = "${v.typeName}")${comma}`);
    }
    lines.push(`})`);
    lines.push(GENERATED_ANNOTATION);

    // Build the permits clause (all variant classes + UnknownSessionEvent last)
    const allPermitted = [...variants.map((v) => v.className), "UnknownSessionEvent"];
    lines.push(`public abstract sealed class SessionEvent permits`);
    for (let i = 0; i < allPermitted.length; i++) {
        const comma = i < allPermitted.length - 1 ? "," : " {";
        lines.push(`        ${allPermitted[i]}${comma}`);
    }
    lines.push("");
    lines.push(`    /** Unique event identifier (UUID v4), generated when the event is emitted. */`);
    lines.push(`    @JsonProperty("id")`);
    lines.push(`    private UUID id;`);
    lines.push("");
    lines.push(`    /** ISO 8601 timestamp when the event was created. */`);
    lines.push(`    @JsonProperty("timestamp")`);
    lines.push(`    private OffsetDateTime timestamp;`);
    lines.push("");
    lines.push(`    /** ID of the chronologically preceding event in the session. Null for the first event. */`);
    lines.push(`    @JsonProperty("parentId")`);
    lines.push(`    private UUID parentId;`);
    lines.push("");
    lines.push(`    /** Sub-agent instance identifier. Absent for events from the root/main agent and session-level events. */`);
    lines.push(`    @JsonProperty("agentId")`);
    lines.push(`    private String agentId;`);
    lines.push("");
    lines.push(`    /** When true, the event is transient and not persisted to the session event log on disk. */`);
    lines.push(`    @JsonProperty("ephemeral")`);
    lines.push(`    private Boolean ephemeral;`);
    lines.push("");
    lines.push(`    /**`);
    lines.push(`     * Returns the event-type discriminator string (e.g., {@code "session.idle"}).`);
    lines.push(`     *`);
    lines.push(`     * @return the event type`);
    lines.push(`     */`);
    lines.push(`    public abstract String getType();`);
    lines.push("");
    lines.push(`    public UUID getId() { return id; }`);
    lines.push(`    public void setId(UUID id) { this.id = id; }`);
    lines.push("");
    lines.push(`    public OffsetDateTime getTimestamp() { return timestamp; }`);
    lines.push(`    public void setTimestamp(OffsetDateTime timestamp) { this.timestamp = timestamp; }`);
    lines.push("");
    lines.push(`    public UUID getParentId() { return parentId; }`);
    lines.push(`    public void setParentId(UUID parentId) { this.parentId = parentId; }`);
    lines.push("");
    lines.push(`    public String getAgentId() { return agentId; }`);
    lines.push(`    public void setAgentId(String agentId) { this.agentId = agentId; }`);
    lines.push("");
    lines.push(`    public Boolean getEphemeral() { return ephemeral; }`);
    lines.push(`    public void setEphemeral(Boolean ephemeral) { this.ephemeral = ephemeral; }`);
    lines.push(`}`);
    lines.push("");

    await writeGeneratedFile(`${packageDir}/SessionEvent.java`, lines.join("\n"));

    // Also generate the UnknownSessionEvent fallback
    await generateUnknownEventClass(packageName, packageDir);
}

async function generateUnknownEventClass(packageName: string, packageDir: string): Promise<void> {
    const lines: string[] = [];
    lines.push(COPYRIGHT);
    lines.push("");
    lines.push(AUTO_GENERATED_HEADER);
    lines.push(GENERATED_FROM_SESSION_EVENTS);
    lines.push("");
    lines.push(`package ${packageName};`);
    lines.push("");
    lines.push(`import com.fasterxml.jackson.annotation.JsonIgnoreProperties;`);
    lines.push(`import com.fasterxml.jackson.annotation.JsonProperty;`);
    lines.push(`import javax.annotation.processing.Generated;`);
    lines.push("");
    lines.push(`/**`);
    lines.push(` * Fallback for event types not yet known to this SDK version.`);
    lines.push(` * <p>`);
    lines.push(` * {@link #getType()} returns the original type string from the JSON payload,`);
    lines.push(` * preserving forward compatibility with event types introduced by newer CLI versions.`);
    lines.push(` *`);
    lines.push(` * @since 1.0.0`);
    lines.push(` */`);
    lines.push(`@JsonIgnoreProperties(ignoreUnknown = true)`);
    lines.push(GENERATED_ANNOTATION);
    lines.push(`public final class UnknownSessionEvent extends SessionEvent {`);
    lines.push("");
    lines.push(`    @JsonProperty("type")`);
    lines.push(`    private String type = "unknown";`);
    lines.push("");
    lines.push(`    @Override`);
    lines.push(`    public String getType() { return type; }`);
    lines.push(`}`);
    lines.push("");

    await writeGeneratedFile(`${packageDir}/UnknownSessionEvent.java`, lines.join("\n"));
}

/** Render a nested type (enum or record) indented at the given level. */
function renderNestedType(nested: JavaClassDef, indentLevel: number, nestedTypes: Map<string, JavaClassDef>, allImports: Set<string>): string[] {
    const ind = "    ".repeat(indentLevel);
    const lines: string[] = [];

    if (nested.kind === "enum") {
        lines.push("");
        if (nested.description) {
            lines.push(`${ind}/** ${nested.description} */`);
        }
        lines.push(`${ind}public enum ${nested.name} {`);
        for (let i = 0; i < (nested.values || []).length; i++) {
            const v = nested.values![i];
            const comma = i < nested.values!.length - 1 ? "," : ";";
            lines.push(`${ind}    /** The {@code ${v}} variant. */`);
            lines.push(`${ind}    ${toEnumConstant(v)}("${v}")${comma}`);
        }
        lines.push("");
        lines.push(`${ind}    private final String value;`);
        lines.push(`${ind}    ${nested.name}(String value) { this.value = value; }`);
        lines.push(`${ind}    @com.fasterxml.jackson.annotation.JsonValue`);
        lines.push(`${ind}    public String getValue() { return value; }`);
        lines.push(`${ind}    @com.fasterxml.jackson.annotation.JsonCreator`);
        lines.push(`${ind}    public static ${nested.name} fromValue(String value) {`);
        lines.push(`${ind}        for (${nested.name} v : values()) {`);
        lines.push(`${ind}            if (v.value.equals(value)) return v;`);
        lines.push(`${ind}        }`);
        lines.push(`${ind}        throw new IllegalArgumentException("Unknown ${nested.name} value: " + value);`);
        lines.push(`${ind}    }`);
        lines.push(`${ind}}`);
    } else if (nested.kind === "class" && nested.schema?.properties) {
        const localNestedTypes = new Map<string, JavaClassDef>();
        const fields: { jsonName: string; javaName: string; javaType: string; description?: string }[] = [];

        for (const [propName, propSchema] of Object.entries(nested.schema.properties)) {
            if (typeof propSchema !== "object") continue;
            const prop = propSchema as JSONSchema7;
            // Record components are always boxed (nullable by design).
            const result = schemaTypeToJava(prop, false, nested.name, propName, localNestedTypes);
            for (const imp of result.imports) allImports.add(imp);
            fields.push({ jsonName: propName, javaName: toCamelCase(propName), javaType: result.javaType, description: prop.description });
        }

        lines.push("");
        if (nested.description) {
            lines.push(`${ind}/** ${nested.description} */`);
        }
        lines.push(`${ind}@JsonIgnoreProperties(ignoreUnknown = true)`);
        lines.push(`${ind}@JsonInclude(JsonInclude.Include.NON_NULL)`);
        if (fields.length === 0) {
            lines.push(`${ind}public record ${nested.name}() {`);
        } else {
            lines.push(`${ind}public record ${nested.name}(`);
            for (let i = 0; i < fields.length; i++) {
                const f = fields[i];
                const comma = i < fields.length - 1 ? "," : "";
                if (f.description) lines.push(`${ind}    /** ${f.description} */`);
                lines.push(`${ind}    @JsonProperty("${f.jsonName}") ${f.javaType} ${f.javaName}${comma}`);
            }
            lines.push(`${ind}) {`);
        }
        // Render any further nested types inside this record
        for (const [, localNested] of localNestedTypes) {
            lines.push(...renderNestedType(localNested, indentLevel + 1, nestedTypes, allImports));
        }
        if (lines[lines.length - 1] !== "") lines.push("");
        lines.pop(); // remove trailing blank before closing brace
        lines.push(`${ind}}`);
    }

    return lines;
}

async function generateEventVariantClass(
    variant: EventVariant,
    packageName: string,
    packageDir: string
): Promise<void> {
    await writeGeneratedFile(`${packageDir}/${variant.className}.java`, renderEventVariantClass(variant, packageName));
}

export function renderEventVariantClass(variant: EventVariant, packageName: string): string {
    const lines: string[] = [];
    const allImports = new Set<string>([
        "com.fasterxml.jackson.annotation.JsonIgnoreProperties",
        "com.fasterxml.jackson.annotation.JsonProperty",
        "com.fasterxml.jackson.annotation.JsonInclude",
        "javax.annotation.processing.Generated",
    ]);
    const nestedTypes = new Map<string, JavaClassDef>();
    const hasUnionData = [variant.dataSchema?.anyOf, variant.dataSchema?.oneOf].some(
        (alternatives) => alternatives && alternatives.filter((alternative) => {
            if (typeof alternative === "boolean") return alternative;
            const types = Array.isArray(alternative.type) ? alternative.type : [alternative.type];
            return !(
                types.every((type) => type === "null") ||
                alternative.const === null ||
                alternative.enum?.every((value) => value === null)
            );
        }).length > 1
    );
    if (hasUnionData) {
        allImports.add("com.fasterxml.jackson.annotation.JsonCreator");
        allImports.add("com.fasterxml.jackson.annotation.JsonValue");
        allImports.add("com.fasterxml.jackson.databind.JsonNode");
        allImports.add("com.fasterxml.jackson.databind.node.JsonNodeFactory");
    }

    // Collect data record fields
    interface FieldInfo {
        jsonName: string;
        javaName: string;
        javaType: string;
        description?: string;
        experimental: boolean;
    }

    const dataFields: FieldInfo[] = [];

    if (!hasUnionData && variant.dataSchema?.properties) {
        for (const [propName, propSchema] of Object.entries(variant.dataSchema.properties)) {
            if (typeof propSchema !== "object") continue;
            const prop = propSchema as JSONSchema7;
            // Record components are always boxed (nullable by design).
            const result = schemaTypeToJava(prop, false, `${variant.className}Data`, propName, nestedTypes);
            for (const imp of result.imports) allImports.add(imp);
            dataFields.push({
                jsonName: propName,
                javaName: toCamelCase(propName),
                javaType: result.javaType,
                description: prop.description,
                experimental: isSchemaExperimental(prop),
            });
        }
    }

    // Whether a data record should be emitted (always when dataSchema is present)
    const hasDataSchema = variant.dataSchema !== null;

    // Build the file
    lines.push(COPYRIGHT);
    lines.push("");
    lines.push(AUTO_GENERATED_HEADER);
    lines.push(GENERATED_FROM_SESSION_EVENTS);
    lines.push("");
    lines.push(`package ${packageName};`);
    lines.push("");

    // Placeholder for imports
    const importPlaceholderIdx = lines.length;
    lines.push("__IMPORTS__");
    lines.push("");

    if (variant.description) {
        lines.push(`/**`);
        lines.push(` * ${variant.description}`);
    } else {
        lines.push(`/**`);
        lines.push(` * The {@code ${variant.typeName}} session event.`);
    }
    if (variant.stability === "experimental") {
        lines.push(` *`);
        lines.push(` * @apiNote This method is experimental and may change in a future version.`);
    }
    lines.push(` * @since 1.0.0`);
    lines.push(` */`);
    if (variant.deprecated) {
        lines.push(`@Deprecated`);
    }
    if (variant.stability === "experimental") {
        allImports.add("com.github.copilot.CopilotExperimental");
        lines.push(`@CopilotExperimental`);
    }
    lines.push(`@JsonIgnoreProperties(ignoreUnknown = true)`);
    lines.push(`@JsonInclude(JsonInclude.Include.NON_NULL)`);
    lines.push(GENERATED_ANNOTATION);
    lines.push(`public final class ${variant.className} extends SessionEvent {`);
    lines.push("");
    lines.push(`    @Override`);
    lines.push(`    public String getType() { return "${variant.typeName}"; }`);

    if (hasDataSchema) {
        lines.push("");
        lines.push(`    @JsonProperty("data")`);
        lines.push(`    private ${variant.className}Data data;`);
        lines.push("");
        lines.push(`    public ${variant.className}Data getData() { return data; }`);
        lines.push(`    public void setData(${variant.className}Data data) { this.data = data; }`);
        lines.push("");
        // Generate data inner record
        lines.push(hasUnionData
            ? `    /** Raw union payload for {@link ${variant.className}}, preserving every variant's fields. */`
            : `    /** Data payload for {@link ${variant.className}}. */`);
        lines.push(`    @JsonIgnoreProperties(ignoreUnknown = true)`);
        lines.push(`    @JsonInclude(JsonInclude.Include.NON_NULL)`);
        if (hasUnionData) {
            // Keep the existing nested record and no-arg constructor binary-compatible.
            lines.push(`    public record ${variant.className}Data(JsonNode raw) {`);
            lines.push(`        @JsonCreator(mode = JsonCreator.Mode.DELEGATING)`);
            lines.push(`        public ${variant.className}Data {}`);
            lines.push("");
            lines.push(`        public ${variant.className}Data() {`);
            lines.push(`            this(JsonNodeFactory.instance.objectNode());`);
            lines.push(`        }`);
            lines.push("");
            lines.push(`        @JsonValue`);
            lines.push(`        public JsonNode raw() { return raw; }`);
        } else if (dataFields.length === 0) {
            lines.push(`    public record ${variant.className}Data() {`);
        } else {
            lines.push(`    public record ${variant.className}Data(`);
            for (let i = 0; i < dataFields.length; i++) {
                const field = dataFields[i];
                const comma = i < dataFields.length - 1 ? "," : "";
                if (field.description) {
                    lines.push(`        /** ${field.description} */`);
                }
                if (field.experimental) {
                    allImports.add("com.github.copilot.CopilotExperimental");
                    lines.push(`        @CopilotExperimental`);
                }
                lines.push(`        @JsonProperty("${field.jsonName}") ${field.javaType} ${field.javaName}${comma}`);
            }
            lines.push(`    ) {`);
        }
        // Render nested types inside Data record
        for (const [, nested] of nestedTypes) {
            lines.push(...renderNestedType(nested, 2, nestedTypes, allImports));
        }
        if (nestedTypes.size > 0 && lines[lines.length - 1] === "") lines.pop();
        lines.push(`    }`);
    }

    lines.push(`}`);
    lines.push("");

    // Replace import placeholder
    const sortedImports = [...allImports].sort();
    const importLines = sortedImports.map((i) => `import ${i};`).join("\n");
    lines[importPlaceholderIdx] = importLines;

    return lines.join("\n");
}

// ── Standalone $ref type generation ──────────────────────────────────────────

/**
 * Generate all pending standalone types discovered via $ref resolution.
 * Iterates until no new types are discovered (handles transitive $ref chains).
 */
async function generatePendingStandaloneTypes(
    packageName: string,
    packageDir: string,
    headerComment: string
): Promise<void> {
    const generated = new Set<string>();

    while (true) {
        const batch: [string, JSONSchema7][] = [];
        for (const [name, schema] of pendingStandaloneTypes) {
            if (!generated.has(name)) {
                batch.push([name, schema]);
                generated.add(name);
            }
        }
        pendingStandaloneTypes.clear();

        if (batch.length === 0) break;

        for (const [name, schema] of batch) {
            if (schema.type === "string" && schema.enum) {
                await generateStandaloneEnum(name, schema, packageName, packageDir, headerComment);
            } else if (schema.type === "object" && schema.properties) {
                await generateStandaloneRecord(name, schema, packageName, packageDir, headerComment);
            } else if (unionVariants(schema)) {
                const variants = resolveUnionVariants(schema);
                if (variants && variants.length > 1 && promotedSealedUnionTypes.has(name) && findRequiredStringDiscriminator(variants)) {
                    await generateSealedUnionInterface(name, schema, packageName, packageDir, headerComment);
                } else if (variants && variants.length > 1 && findDiscriminator(variants)) {
                    await generatePolymorphicResultClass(name, schema, packageName, packageDir);
                } else {
                    console.warn(`[codegen] Cannot generate standalone type for ${name}: union without discriminator`);
                }
            } else {
                console.warn(`[codegen] Cannot generate standalone type for ${name}: type=${schema.type}`);
            }
        }
        // Generating records may have discovered more $ref targets — loop again
    }
}

async function generateStandaloneEnum(
    name: string,
    schema: JSONSchema7,
    packageName: string,
    packageDir: string,
    headerComment: string
): Promise<void> {
    const values = schema.enum as string[];
    const experimental = isSchemaExperimental(schema);
    const lines: string[] = [];
    lines.push(COPYRIGHT);
    lines.push("");
    lines.push(AUTO_GENERATED_HEADER);
    lines.push(headerComment);
    lines.push("");
    lines.push(`package ${packageName};`);
    lines.push("");
    if (experimental) {
        lines.push(`import com.github.copilot.CopilotExperimental;`);
    }
    lines.push(`import javax.annotation.processing.Generated;`);
    lines.push("");
    if (schema.description || experimental) {
        lines.push(`/**`);
        lines.push(` * ${schema.description ?? `Values for {@code ${name}}.`}`);
        appendExperimentalTypeApiNote(lines, schema);
        lines.push(` *`);
        lines.push(` * @since 1.0.0`);
        lines.push(` */`);
    }
    if (experimental) {
        lines.push(`@CopilotExperimental`);
    }
    lines.push(GENERATED_ANNOTATION);
    lines.push(`public enum ${name} {`);
    for (let i = 0; i < values.length; i++) {
        const v = values[i];
        const comma = i < values.length - 1 ? "," : ";";
        lines.push(`    /** The {@code ${v}} variant. */`);
        lines.push(`    ${toEnumConstant(v)}("${v}")${comma}`);
    }
    lines.push("");
    lines.push(`    private final String value;`);
    lines.push(`    ${name}(String value) { this.value = value; }`);
    lines.push(`    @com.fasterxml.jackson.annotation.JsonValue`);
    lines.push(`    public String getValue() { return value; }`);
    lines.push(`    @com.fasterxml.jackson.annotation.JsonCreator`);
    lines.push(`    public static ${name} fromValue(String value) {`);
    lines.push(`        for (${name} v : values()) {`);
    lines.push(`            if (v.value.equals(value)) return v;`);
    lines.push(`        }`);
    lines.push(`        throw new IllegalArgumentException("Unknown ${name} value: " + value);`);
    lines.push(`    }`);
    lines.push(`}`);
    lines.push("");

    await writeGeneratedFile(`${packageDir}/${name}.java`, lines.join("\n"));
}

async function generateStandaloneRecord(
    name: string,
    schema: JSONSchema7,
    packageName: string,
    packageDir: string,
    headerComment: string
): Promise<void> {
    const nestedTypes = new Map<string, { code: string }>();
    const { code, imports } = generateRpcClass(name, schema, nestedTypes, packageName);
    const experimental = isSchemaExperimental(schema);

    const lines: string[] = [];
    lines.push(COPYRIGHT);
    lines.push("");
    lines.push(AUTO_GENERATED_HEADER);
    lines.push(headerComment);
    lines.push("");
    lines.push(`package ${packageName};`);
    lines.push("");

    const allImports = new Set<string>([
        "com.fasterxml.jackson.annotation.JsonIgnoreProperties",
        "com.fasterxml.jackson.annotation.JsonProperty",
        "com.fasterxml.jackson.annotation.JsonInclude",
        "javax.annotation.processing.Generated",
        ...imports,
    ]);
    if (experimental) {
        allImports.add("com.github.copilot.CopilotExperimental");
    }
    const sortedImports = [...allImports].sort();
    for (const imp of sortedImports) {
        lines.push(`import ${imp};`);
    }
    lines.push("");

    if (schema.description || experimental) {
        lines.push(`/**`);
        lines.push(` * ${schema.description ?? `Data type {@code ${name}}.`}`);
        appendExperimentalTypeApiNote(lines, schema);
        lines.push(` *`);
        lines.push(` * @since 1.0.0`);
        lines.push(` */`);
    }
    if (experimental) {
        lines.push(`@CopilotExperimental`);
    }
    lines.push(GENERATED_ANNOTATION);
    lines.push(code);
    lines.push("");

    await writeGeneratedFile(`${packageDir}/${name}.java`, lines.join("\n"));
}

// ── RPC types codegen ─────────────────────────────────────────────────────────

interface RpcMethod {
    rpcMethod: string;
    params: JSONSchema7 | null;
    result: JSONSchema7 | null;
    stability?: string;
    deprecated?: boolean;
}

function isRpcMethod(node: unknown): node is RpcMethod {
    return typeof node === "object" && node !== null && "rpcMethod" in node;
}

function collectRpcMethods(node: Record<string, unknown>): [string, RpcMethod][] {
    const results: [string, RpcMethod][] = [];
    for (const [key, value] of Object.entries(node)) {
        if (isRpcMethod(value)) {
            results.push([key, value]);
        } else if (typeof value === "object" && value !== null) {
            results.push(...collectRpcMethods(value as Record<string, unknown>));
        }
    }
    return results;
}

/** Convert an RPC method name to a Java class name prefix (e.g., "models.list" -> "ModelsList") */
function rpcMethodToClassName(rpcMethod: string): string {
    return rpcMethod.split(/[._-]/).map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join("");
}

function schemaAllowsNull(schema: JSONSchema7): boolean {
    if (schema.type === "null" || (Array.isArray(schema.type) && schema.type.includes("null"))) {
        return true;
    }
    if (schema.const === null || schema.enum?.includes(null)) {
        return true;
    }
    return [...(schema.anyOf || []), ...(schema.oneOf || [])].some(
        (variant) => typeof variant === "object" && schemaAllowsNull(variant)
    );
}

/** Generate a Java record for a JSON Schema object type. Returns the class content. */
export function generateRpcClass(
    className: string,
    schema: JSONSchema7,
    _nestedTypes: Map<string, { code: string }>,
    _packageName: string,
    visibility: "public" | "internal" = "public",
    preserveRequiredNulls = false,
    omittedProperties: ReadonlySet<string> = new Set()
): { code: string; imports: Set<string> } {
    const imports = new Set<string>();
    const localNestedTypes = new Map<string, JavaClassDef>();
    const lines: string[] = [];
    const visModifier = visibility === "public" ? "public " : "";

    const properties = Object.entries(schema.properties || {}).filter(([propName]) => !omittedProperties.has(propName));
    const required = new Set(schema.required || []);
    const fields = properties.flatMap(([propName, propSchema]) => {
        if (typeof propSchema !== "object") return [];
        const prop = propSchema as JSONSchema7;
        // Record components are always boxed (nullable by design).
        const result = schemaTypeToJava(prop, false, className, propName, localNestedTypes);
        for (const imp of result.imports) imports.add(imp);
        return [{
            propName,
            javaName: toCamelCase(propName),
            javaType: result.javaType,
            description: prop.description,
            includeNull: preserveRequiredNulls && required.has(propName) && schemaAllowsNull(prop),
        }];
    });

    lines.push(`@JsonInclude(JsonInclude.Include.NON_NULL)`);
    lines.push(`@JsonIgnoreProperties(ignoreUnknown = true)`);
    if (fields.length === 0) {
        lines.push(`${visModifier}record ${className}() {`);
    } else {
        lines.push(`${visModifier}record ${className}(`);
        for (let i = 0; i < fields.length; i++) {
            const f = fields[i];
            const comma = i < fields.length - 1 ? "," : "";
            if (f.description) {
                lines.push(`    /** ${f.description} */`);
            }
            if (f.includeNull) {
                lines.push(`    @JsonInclude(JsonInclude.Include.ALWAYS)`);
            }
            lines.push(`    @JsonProperty("${f.propName}") ${f.javaType} ${f.javaName}${comma}`);
        }
        lines.push(`) {`);
    }

    // Add nested types as nested records/enums inside this record
    for (const [, nested] of localNestedTypes) {
        lines.push(...renderNestedType(nested, 1, new Map(), imports));
    }

    if (localNestedTypes.size > 0 && lines[lines.length - 1] === "") lines.pop();
    const legacyFieldNames =
        className === "McpOauthRequiredStaticClientConfig"
            ? ["clientId", "clientSecret", "publicClient", "grantType"]
            : undefined;
    if (legacyFieldNames) {
        const legacyFields = legacyFieldNames.map((fieldName) => {
            const field = fields.find((candidate) => candidate.javaName === fieldName);
            if (!field) {
                throw new Error(`Missing legacy field ${className}.${fieldName}`);
            }
            return field;
        });
        const omittedFields = fields.filter((field) => !legacyFieldNames.includes(field.javaName));
        if (omittedFields.length !== 1 || omittedFields[0].javaName !== "scope") {
            throw new Error(`Unexpected compatibility fields for ${className}`);
        }

        lines.push(``);
        lines.push(`    /**`);
        lines.push(`     * Creates a static OAuth client configuration without an explicit scope.`);
        lines.push(`     *`);
        for (const field of legacyFields) {
            const description = (field.description || field.propName)
                .replace(/\s+/g, " ")
                .replaceAll("*/", "* /");
            lines.push(`     * @param ${field.javaName} ${description}`);
        }
        lines.push(`     */`);
        lines.push(`    public ${className}(`);
        legacyFields.forEach((field, index) => {
            lines.push(`        ${field.javaType} ${field.javaName}${index < legacyFields.length - 1 ? "," : ""}`);
        });
        lines.push(`    ) {`);
        lines.push(`        this(${legacyFieldNames.join(", ")}, null);`);
        lines.push(`    }`);
    }

    // A request record drops its additions instead; a response record keeps every component.
    const recordLegacy = omittedProperties.size === 0
        ? readLegacyParameters(schema, className, { ordered: true })
        : undefined;
    if (recordLegacy) {
        if (legacyFieldNames) {
            throw new Error(`Conflicting compatibility constructors for ${className}`);
        }
        const legacyNames = new Set(recordLegacy.legacy);
        const legacyFields = fields.filter((field) => legacyNames.has(field.propName));
        lines.push(``);
        lines.push(`    /**`);
        lines.push(`     * Creates a record with the components it had before later optional fields were added.`);
        lines.push(`     *`);
        for (const field of legacyFields) {
            lines.push(`     * @param ${field.javaName} ${javadocText(field.description || field.propName)}`);
        }
        lines.push(`     */`);
        lines.push(`    public ${className}(`);
        legacyFields.forEach((field, index) => {
            lines.push(`        ${field.javaType} ${field.javaName}${index < legacyFields.length - 1 ? "," : ""}`);
        });
        lines.push(`    ) {`);
        lines.push(`        this(${fields.map((field) => (legacyNames.has(field.propName) ? field.javaName : "null")).join(", ")});`);
        lines.push(`    }`);
    }

    lines.push(`}`);

    return { code: lines.join("\n"), imports };
}

/** Sections whose requests the SDK sends, and the properties the SDK supplies itself. */
const LEGACY_REQUEST_IMPLICIT_PROPERTIES: Readonly<Record<string, readonly string[]>> = {
    server: [],
    session: ["sessionId"],
};

/**
 * Reads a method's `x-legacy-parameters`. The Java projection keeps the existing params
 * record with only the legacy components and adds an extensible request class.
 */
function javaLegacyParameters(
    method: { rpcMethod: string; params: JSONSchema7 | null },
    sectionName: string
): LegacyParameters | undefined {
    const params = resolveMethodParamsSchema(method as RpcMethodNode);
    if (!hasLegacyParameters(params)) return undefined;
    const implicit = LEGACY_REQUEST_IMPLICIT_PROPERTIES[sectionName];
    if (!implicit) {
        throw new Error(`Invalid ${LEGACY_PARAMETERS_KEY} for ${method.rpcMethod}: only server and session requests are supported`);
    }
    if (resolveMethodParamsUnionSchema(method as RpcMethodNode)) {
        throw new Error(`Invalid ${LEGACY_PARAMETERS_KEY} for ${method.rpcMethod}: union requests are not supported`);
    }
    return readLegacyParameters(params, method.rpcMethod, {
        implicit,
        optional: isOmittableRequest(method.params) || methodParamsAreOptional(method as RpcMethodNode),
        nullable: !!method.params && schemaAllowsNull(method.params),
    });
}

/** The extensible request class for a method that declares `x-legacy-parameters`. */
function legacyRequestClassName(method: { rpcMethod: string; params: JSONSchema7 | null }): string {
    return extractRefName(method.params) ?? `${rpcMethodToClassName(method.rpcMethod)}Request`;
}

function javadocText(text: string): string {
    return text.replace(/\s+/g, " ").replaceAll("*/", "* /").trim();
}

/**
 * Generate the extensible request class for a method with `x-legacy-parameters`.
 * Required inputs are constructor arguments; optional inputs have fluent setters, so
 * later optional properties add setters without changing the constructor.
 */
export function generateLegacyRequestClass(
    className: string,
    schema: JSONSchema7,
    legacy: LegacyParameters
): { code: string; imports: Set<string> } {
    const imports = new Set<string>(["java.util.Objects"]);
    const localNestedTypes = new Map<string, JavaClassDef>();
    const properties = schema.properties ?? {};
    const fields = [...legacy.legacy, ...legacy.additions].map((propName) => {
        const prop = properties[propName] as JSONSchema7;
        const result = schemaTypeToJava(prop, false, className, propName, localNestedTypes);
        for (const imp of result.imports) imports.add(imp);
        const required = legacy.required.has(propName);
        return {
            propName,
            javaName: toCamelCase(propName),
            accessor: toPascalCase(propName),
            javaType: result.javaType,
            description: javadocText(prop.description ?? `The {@code ${propName}} property.`),
            required,
            nullable: schemaAllowsNull(prop),
        };
    });
    const required = fields.filter((field) => field.required);
    const optional = fields.filter((field) => !field.required);

    const lines: string[] = [];
    lines.push(`@JsonInclude(JsonInclude.Include.NON_NULL)`);
    lines.push(`public final class ${className} {`);
    for (const field of fields) {
        lines.push(``);
        lines.push(`    /** ${field.description} */`);
        if (field.required && field.nullable) {
            lines.push(`    @JsonInclude(JsonInclude.Include.ALWAYS)`);
        }
        lines.push(`    @JsonProperty("${field.propName}")`);
        lines.push(`    private ${field.required ? "final " : ""}${field.javaType} ${field.javaName};`);
    }

    lines.push(``);
    lines.push(`    /**`);
    lines.push(`     * Creates a request with its required inputs.`);
    if (required.length > 0) lines.push(`     *`);
    for (const field of required) {
        lines.push(`     * @param ${field.javaName} ${field.description}`);
    }
    lines.push(`     */`);
    lines.push(`    public ${className}(${required.map((field) => `${field.javaType} ${field.javaName}`).join(", ")}) {`);
    for (const field of required) {
        const value = field.nullable ? field.javaName : `Objects.requireNonNull(${field.javaName}, "${field.javaName}")`;
        lines.push(`        this.${field.javaName} = ${value};`);
    }
    lines.push(`    }`);

    for (const field of fields) {
        lines.push(``);
        lines.push(`    /**`);
        lines.push(`     * Returns the {@code ${field.propName}} property.`);
        lines.push(`     *`);
        lines.push(`     * @return ${field.description}`);
        lines.push(`     */`);
        lines.push(`    public ${field.javaType} get${field.accessor}() {`);
        lines.push(`        return ${field.javaName};`);
        lines.push(`    }`);
    }

    for (const field of optional) {
        lines.push(``);
        lines.push(`    /**`);
        lines.push(`     * Sets the {@code ${field.propName}} property.`);
        lines.push(`     *`);
        lines.push(`     * @param value ${field.description}`);
        lines.push(`     * @return this request`);
        lines.push(`     */`);
        lines.push(`    public ${className} set${field.accessor}(${field.javaType} value) {`);
        lines.push(`        this.${field.javaName} = value;`);
        lines.push(`        return this;`);
        lines.push(`    }`);
    }

    for (const [, nested] of localNestedTypes) {
        lines.push(...renderNestedType(nested, 1, new Map(), imports));
    }
    lines.push(`}`);

    return { code: lines.join("\n"), imports };
}

interface RpcSchema {
    server?: Record<string, unknown>;
    session?: Record<string, unknown>;
    clientSession?: Record<string, unknown>;
    clientGlobal?: Record<string, unknown>;
    definitions?: Record<string, JSONSchema7>;
}

async function generateRpcTypes(schemaPath: string): Promise<void> {
    console.log("\n🔌 Generating RPC types...");
    const schemaContent = await fs.readFile(schemaPath, "utf-8");
    const schema: RpcSchema = normalizeSchemaBrandCasing(JSON.parse(schemaContent));
    crossSchemaDefinitions.clear();

    // Load cross-schema definitions (session-events) so that cross-schema $ref values
    // like "session-events.schema.json#/definitions/Foo" can be resolved.
    try {
        const sessionEventsSchemaPath = await getSessionEventsSchemaPath();
        const sessionEventsContent = await fs.readFile(sessionEventsSchemaPath, "utf-8");
        const sessionEventsSchema = normalizeSchemaBrandCasing(JSON.parse(sessionEventsContent) as JSONSchema7);
        crossSchemaDefinitions.set("session-events.schema.json",
            (sessionEventsSchema.definitions ?? {}) as Record<string, JSONSchema7>);
    } catch (e) {
        console.warn(`[codegen] Could not load session-events schema for cross-ref resolution: ${e}`);
    }

    const files = await renderRpcTypes(schema);
    for (const [file, content] of files) await writeGeneratedFile(file, content);
    console.log(`✅ Generated ${files.size} RPC type files`);
}

/** Plan and render all RPC types in memory, rejecting ABI/name conflicts before file writes. */
export async function renderRpcTypes(
    schema: RpcSchema,
    historicalOwners: Readonly<Record<string, string>> = RPC_VARIANT_OWNERS
): Promise<Map<string, string>> {
    if (rpcGeneration) throw new Error("Concurrent Java RPC generation is not supported.");
    const generation: RpcGeneration = { files: new Map(), unions: new Map() };
    rpcGeneration = generation;
    try {
        await collectRpcTypes(schema);
        generation.variantNames = planRpcVariantNames(generation, historicalOwners);
        for (const [name, union] of generation.unions) {
            await generatePolymorphicResultClass(name, union.schema, union.packageName, union.packageDir);
        }
        if ((schema.definitions ?? {})["InstallationReview"]) {
            const packageDir = `sdk/src/generated/java/com/github/copilot/generated/rpc`;
            const packageName = "com.github.copilot.generated.rpc";
            generation.files.set(`${packageDir}/InstallationConfirmationRequestReview.java`, [
                COPYRIGHT,
                "",
                "// AUTO-GENERATED FILE - DO NOT EDIT",
                "// Generated from: api.schema.json",
                "",
                `package ${packageName};`,
                "",
                "import com.fasterxml.jackson.annotation.JsonIgnoreProperties;",
                "import com.fasterxml.jackson.annotation.JsonInclude;",
                "import com.fasterxml.jackson.annotation.JsonProperty;",
                "import javax.annotation.processing.Generated;",
                "",
                "/** Compatibility wrapper for installation confirmation review payloads. */",
                "@javax.annotation.processing.Generated(\"copilot-sdk-codegen\")",
                "@JsonInclude(JsonInclude.Include.NON_NULL)",
                "@JsonIgnoreProperties(ignoreUnknown = true)",
                "public record InstallationConfirmationRequestReview(",
                "    /** Resource-specific review to present before collecting the user's decision. */",
                "    @JsonProperty(\"review\") InstallationReview review",
                ") {",
                "}",
                "",
            ].join("\n"));
        }
        return generation.files;
    } finally {
        rpcGeneration = undefined;
    }
}

async function collectRpcTypes(schema: RpcSchema): Promise<void> {
    currentDefinitions = schema.definitions ?? {};
    pendingStandaloneTypes.clear();
    promotedNestedUnionTypes.clear();
    promotedSealedUnionTypes.clear();
    // Session create/resume consumes this named type, not the method-specific result wrapper.
    if (currentDefinitions.DiagnosticsConfiguration) {
        pendingStandaloneTypes.set("DiagnosticsConfiguration", currentDefinitions.DiagnosticsConfiguration);
    }
    const packageName = "com.github.copilot.generated.rpc";
    const packageDir = `sdk/src/generated/java/com/github/copilot/generated/rpc`;

    // Collect all RPC methods from all sections
    const sections: [string, Record<string, unknown>][] = [];
    if (schema.server) sections.push(["server", schema.server]);
    if (schema.session) sections.push(["session", schema.session]);
    if (schema.clientSession) sections.push(["clientSession", schema.clientSession]);
    if (schema.clientGlobal) sections.push(["clientGlobal", schema.clientGlobal]);

    const directMethodRefNames = collectDirectMethodRefNames(schema);
    const excludedSealedUnionSeeds = new Set([
        ...directMethodRefNames,
        ...collectImmediateObjectUnionRefs(directMethodRefNames, currentDefinitions),
        ...collectImmediateMethodObjectUnionRefs(schema, currentDefinitions),
    ]);
    for (const typeName of collectSealedStandaloneUnionTypeNames(currentDefinitions, excludedSealedUnionSeeds)) {
        promotedSealedUnionTypes.add(typeName);
        promotedNestedUnionTypes.add(typeName);
    }

    for (const [, sectionNode] of sections) {
        for (const [, method] of collectRpcMethods(sectionNode)) {
            for (const typeName of collectNestedDiscriminatedUnionTypeNames(method.result, currentDefinitions)) {
                promotedNestedUnionTypes.add(typeName);
            }
        }
    }

    const generatedClasses = new Map<string, boolean>();
    const allFiles: string[] = [];
    const legacyRequests: { className: string; schema: JSONSchema7; legacy: LegacyParameters; method: RpcMethod }[] = [];

    for (const [sectionName, sectionNode] of sections) {
        const methods = collectRpcMethods(sectionNode);
        for (const [, method] of methods) {
            const className = rpcMethodToClassName(method.rpcMethod);

            // Generate params class — resolve $ref if params is a reference
            let paramsSchema = method.params as JSONSchema7 | null;
            const paramsRefName = extractRefName(paramsSchema);
            if (paramsRefName && sectionName === "clientGlobal") {
                const resolvedParamsSchema = resolveRef(paramsSchema ?? undefined);
                if (resolvedParamsSchema?.type === "object" && resolvedParamsSchema.properties) {
                    pendingStandaloneTypes.set(paramsRefName, resolvedParamsSchema);
                }
                paramsSchema = null;
            } else if (paramsSchema?.$ref) {
                paramsSchema = resolveRef(paramsSchema) as JSONSchema7;
            }
            const paramsUnionSchema = resolveMethodParamsUnionSchema(method);
            if (paramsUnionSchema) {
                const paramsClassName = `${className}Params`;
                if (!generatedClasses.has(paramsClassName)) {
                    generatedClasses.set(paramsClassName, true);
                    await generatePolymorphicResultClass(paramsClassName, paramsUnionSchema, packageName, packageDir);
                    allFiles.push(`${paramsClassName}.java`);
                }
                paramsSchema = null;
            }
            if (paramsSchema && !paramsSchema.properties) {
                paramsSchema = resolveMethodParamsSchema(method) ?? paramsSchema;
            }
            if (paramsSchema && typeof paramsSchema === "object" && paramsSchema.properties) {
                const paramsClassName = `${className}Params`;
                const legacy = javaLegacyParameters(method, sectionName);
                if (!generatedClasses.has(paramsClassName)) {
                    generatedClasses.set(paramsClassName, true);
                    allFiles.push(await generateRpcDataClass(paramsClassName, paramsSchema, packageName, packageDir, method.rpcMethod, "params", method.stability, method.deprecated === true, new Set(legacy?.additions)));
                }
                if (legacy) {
                    legacyRequests.push({ className: legacyRequestClassName(method), schema: paramsSchema, legacy, method });
                }
            }

            // Generate result class — resolve $ref if result is a reference
            let resultSchema = method.result as JSONSchema7 | null;
            const resultRefName = extractRefName(resultSchema);
            if (resultSchema?.$ref) resultSchema = resolveRef(resultSchema) as JSONSchema7;
            if (resultSchema && typeof resultSchema === "object") {
                const nullableRef = nullableResultReference(resultSchema);
                if (nullableRef) {
                    schemaTypeToJava(nullableRef, false, `${className}Result`, "value", new Map());
                    continue;
                }
                if (
                    resultSchema.properties &&
                    (Object.keys(resultSchema.properties).length > 0 ||
                        (resultRefName && sectionName === "clientGlobal"))
                ) {
                    // Object with properties → generate a record class
                    const resultClassName = `${className}Result`;
                    if (!generatedClasses.has(resultClassName)) {
                        generatedClasses.set(resultClassName, true);
                        allFiles.push(await generateRpcDataClass(resultClassName, resultSchema, packageName, packageDir, method.rpcMethod, "result", method.stability, method.deprecated === true));
                    }
                } else if (resultRefName && resultSchema.type === "string" && resultSchema.enum) {
                    // String enum → register for standalone generation
                    pendingStandaloneTypes.set(resultRefName, resultSchema);
                } else if (resultRefName && unionVariants(resultSchema)) {
                    // anyOf discriminated union → generate polymorphic hierarchy
                    const variants = resolveAnyOfVariants(unionVariants(resultSchema) ?? []);
                    if (variants.length > 1 && findDiscriminator(variants)) {
                        if (!generatedClasses.has(resultRefName)) {
                            generatedClasses.set(resultRefName, true);
                            await generatePolymorphicResultClass(resultRefName, resultSchema, packageName, packageDir);
                        }
                    }
                } else if (resultRefName && resultSchema.type === "object" && !resultSchema.properties) {
                    // Empty named object → generate empty record
                    if (!generatedClasses.has(resultRefName)) {
                        generatedClasses.set(resultRefName, true);
                        allFiles.push(await generateRpcDataClass(resultRefName, resultSchema, packageName, packageDir, method.rpcMethod, "result"));
                    }
                } else if (resultRefName && resultSchema.type === "array") {
                    // Named array aliases (e.g. AccountGetAllUsersResult) are returned
                    // as List<T> by wrappers, but resolving them here discovers any
                    // referenced item records that need standalone generation.
                    schemaTypeToJava(resultSchema, false, resultRefName, "item", new Map());
                } else if (resultSchema.type === "array") {
                    // Inline arrays also need their referenced item records generated.
                    schemaTypeToJava(resultSchema, false, `${className}Result`, "item", new Map());
                }
            }
        }
    }

    // Generate standalone types discovered via $ref resolution
    await generatePendingStandaloneTypes(packageName, packageDir, GENERATED_FROM_API);

    // Request classes are written last so any generated type with the same name is a conflict.
    for (const request of legacyRequests) {
        await generateLegacyRequestFile(request.className, request.schema, request.legacy, request.method, packageName, packageDir);
    }
}

async function generateLegacyRequestFile(
    className: string,
    schema: JSONSchema7,
    legacy: LegacyParameters,
    method: RpcMethod,
    packageName: string,
    packageDir: string
): Promise<void> {
    const relativePath = `${packageDir}/${className}.java`;
    if (rpcGeneration?.files.has(relativePath)) {
        throw new Error(`Conflicting Java RPC output "${relativePath}" for the ${method.rpcMethod} request class.`);
    }
    const { code, imports } = generateLegacyRequestClass(className, schema, legacy);
    const experimental = method.stability === "experimental";

    const lines: string[] = [];
    lines.push(COPYRIGHT);
    lines.push("");
    lines.push(AUTO_GENERATED_HEADER);
    lines.push(GENERATED_FROM_API);
    lines.push("");
    lines.push(`package ${packageName};`);
    lines.push("");
    const allImports = new Set<string>([
        "com.fasterxml.jackson.annotation.JsonInclude",
        "com.fasterxml.jackson.annotation.JsonProperty",
        "javax.annotation.processing.Generated",
        ...imports,
    ]);
    if (experimental) allImports.add("com.github.copilot.CopilotExperimental");
    for (const imp of [...allImports].sort()) {
        lines.push(`import ${imp};`);
    }
    lines.push("");
    lines.push(`/**`);
    lines.push(` * ${schema.description ? javadocText(schema.description) : `Request for the {@code ${method.rpcMethod}} RPC method.`}`);
    lines.push(` * <p>`);
    lines.push(` * Required inputs are constructor arguments. Optional inputs have fluent setters.`);
    if (experimental) {
        lines.push(` *`);
        lines.push(` * @apiNote This method is experimental and may change in a future version.`);
    }
    lines.push(` * @since 1.0.0`);
    lines.push(` */`);
    if (method.deprecated) lines.push(`@Deprecated`);
    if (experimental) lines.push(`@CopilotExperimental`);
    lines.push(GENERATED_ANNOTATION);
    lines.push(code);
    lines.push("");

    await writeGeneratedFile(relativePath, lines.join("\n"));
}

async function generateRpcDataClass(
    className: string,
    schema: JSONSchema7,
    packageName: string,
    packageDir: string,
    rpcMethod: string,
    kind: "params" | "result",
    stability?: string,
    deprecated?: boolean,
    omittedProperties: ReadonlySet<string> = new Set()
): Promise<string> {
    const nestedTypes = new Map<string, { code: string }>();
    const { code, imports } = generateRpcClass(className, schema, nestedTypes, packageName, "public", kind === "params", omittedProperties);

    const lines: string[] = [];
    lines.push(COPYRIGHT);
    lines.push("");
    lines.push(AUTO_GENERATED_HEADER);
    lines.push(GENERATED_FROM_API);
    lines.push("");
    lines.push(`package ${packageName};`);
    lines.push("");

    const allImports = new Set<string>([
        "com.fasterxml.jackson.annotation.JsonIgnoreProperties",
        "com.fasterxml.jackson.annotation.JsonProperty",
        "com.fasterxml.jackson.annotation.JsonInclude",
        "javax.annotation.processing.Generated",
        ...imports,
    ]);
    if (stability === "experimental") {
        allImports.add("com.github.copilot.CopilotExperimental");
    }
    const sortedImports = [...allImports].sort();
    for (const imp of sortedImports) {
        lines.push(`import ${imp};`);
    }
    lines.push("");

    if (schema.description) {
        lines.push(`/**`);
        lines.push(` * ${schema.description}`);
    } else {
        lines.push(`/**`);
        lines.push(` * ${kind === "params" ? "Request parameters" : "Result"} for the {@code ${rpcMethod}} RPC method.`);
    }
    if (stability === "experimental") {
        lines.push(` *`);
        lines.push(` * @apiNote This method is experimental and may change in a future version.`);
    }
    lines.push(` * @since 1.0.0`);
    lines.push(` */`);
    if (deprecated) {
        lines.push(`@Deprecated`);
    }
    if (stability === "experimental") {
        lines.push(`@CopilotExperimental`);
    }
    lines.push(GENERATED_ANNOTATION);
    lines.push(code);
    lines.push("");

    await writeGeneratedFile(`${packageDir}/${className}.java`, lines.join("\n"));
    return className;
}

// ── RPC wrapper generation ───────────────────────────────────────────────────

/** A single RPC method node parsed from the schema */
interface RpcMethodNode {
    rpcMethod: string;
    visibility: string;
    stability: string;
    deprecated: boolean;
    params: JSONSchema7 | null;
    result: JSONSchema7 | null;
}

/** Namespace tree node: holds direct methods and sub-namespace trees */
interface NamespaceTree {
    methods: Map<string, RpcMethodNode>;   // leaf method name -> info
    subspaces: Map<string, NamespaceTree>; // sub-namespace name -> tree
}

/** Build a namespace tree by recursively walking a schema section object */
function buildNamespaceTree(node: Record<string, unknown>): NamespaceTree {
    const tree: NamespaceTree = { methods: new Map(), subspaces: new Map() };
    for (const [key, value] of Object.entries(node)) {
        if (typeof value !== "object" || value === null) continue;
        const obj = value as Record<string, unknown>;
        if ("rpcMethod" in obj) {
            tree.methods.set(key, {
                rpcMethod: String(obj.rpcMethod),
                visibility: String(obj.visibility ?? "public"),
                stability: String(obj.stability ?? "stable"),
                deprecated: obj.deprecated === true,
                params: (obj.params as JSONSchema7) ?? null,
                result: (obj.result as JSONSchema7) ?? null,
            });
        } else {
            const child = buildNamespaceTree(obj);
            // Only add non-empty sub-trees
            if (child.methods.size > 0 || child.subspaces.size > 0) {
                tree.subspaces.set(key, child);
            }
        }
    }
    return tree;
}

/**
 * Derive the Java class name for an API namespace class.
 * e.g., prefix="Server", path=["mcp","config"] → "ServerMcpConfigApi"
 */
function apiClassName(prefix: string, path: string[]): string {
    const parts = [prefix, ...path].map((p) => p.charAt(0).toUpperCase() + p.slice(1));
    return parts.join("") + "Api";
}

/**
 * Derive the Java result type for an RPC method.
 * Handles $ref to named definitions (enums, anyOf unions, objects with properties, arrays).
 * Falls back to Void for null results or schemas with no meaningful type.
 */
function wrapperResultClassName(method: RpcMethodNode): string {
    const originalResult = method.result;
    if (!originalResult) return "Void";

    // If result is a $ref, use the definition name directly
    const refName = extractRefName(originalResult);
    if (refName) {
        const resolved = currentDefinitions[refName];
        if (resolved) {
            const nullableRef = nullableResultReference(resolved);
            if (nullableRef) {
                return schemaTypeToJava(nullableRef, false, refName, "value", new Map()).javaType;
            }
            // String enum → use the definition name
            if (resolved.type === "string" && resolved.enum) {
                return refName;
            }
            // anyOf discriminated union → use the definition name
            if (unionVariants(resolved)) {
                const variants = resolveAnyOfVariants(unionVariants(resolved) ?? []);
                if (variants.length > 1 && findDiscriminator(variants)) {
                    return refName;
                }
            }
            // Object with properties → use MethodNameResult
            if (resolved.type === "object" && resolved.properties && Object.keys(resolved.properties).length > 0) {
                return rpcMethodToClassName(method.rpcMethod) + "Result";
            }
            // Empty object (no properties) that is a named definition → use definition name
            if (resolved.type === "object" && !resolved.properties) {
                return refName;
            }
            // Named array aliases → use the underlying List<T> Java type.
            if (resolved.type === "array") {
                const result = schemaTypeToJava(resolved, false, refName, "item", new Map());
                return result.javaType;
            }
        }
    }

    // Inline result schema with properties
    let result = originalResult;
    if (result.$ref) result = resolveRef(result) as JSONSchema7;
    if (
        result &&
        typeof result === "object" &&
        result.properties &&
        Object.keys(result.properties).length > 0
    ) {
        return rpcMethodToClassName(method.rpcMethod) + "Result";
    }

    if (result && typeof result === "object" && result.type === "array") {
        const javaResult = schemaTypeToJava(result, false, `${rpcMethodToClassName(method.rpcMethod)}Result`, "item", new Map());
        return javaResult.javaType;
    }

    // Free-form object with additionalProperties (e.g., x-opaque-json) → JsonNode
    if (
        result &&
        typeof result === "object" &&
        result.type === "object" &&
        result.additionalProperties &&
        !result.properties
    ) {
        return "JsonNode";
    }

    return "Void";
}

function wrapperResultTypeExpression(resultType: string): string {
    const listMatch = resultType.match(/^List<([^<>]+)>$/);
    if (listMatch) {
        return `RpcMapper.INSTANCE.getTypeFactory().constructCollectionType(List.class, ${javaClassLiteral(listMatch[1])})`;
    }

    return javaClassLiteral(resultType);
}

function javaClassLiteral(javaType: string): string {
    return javaType === "Void" ? "Void.class" : `${javaType}.class`;
}

function addWrapperResultImports(resultType: string, allImports: Set<string>, packageName: string): void {
    if (resultType === "Void") {
        return;
    }

    if (resultType === "JsonNode") {
        allImports.add("com.fasterxml.jackson.databind.JsonNode");
        return;
    }

    if (resultType.startsWith("List<")) {
        allImports.add("java.util.List");
    }

    const builtInTypes = new Set(["Boolean", "Double", "Long", "List", "Object", "String", "Void"]);
    for (const typeName of resultType.match(/\b[A-Z][A-Za-z0-9_]*\b/g) ?? []) {
        if (!builtInTypes.has(typeName)) {
            allImports.add(`${packageName}.${typeName}`);
        }
    }
}

/**
 * Return the params class name if the method has a params schema with user-supplied properties.
 * Session-scoped wrappers inject sessionId automatically, but server-scoped wrappers must let
 * callers supply it explicitly.
 */
function wrapperParamsClassName(method: RpcMethodNode, isSession: boolean): string | null {
    if (resolveMethodParamsUnionSchema(method)) {
        return rpcMethodToClassName(method.rpcMethod) + "Params";
    }
    const params = resolveMethodParamsSchema(method);
    if (!params) return null;
    const props = params.properties ?? {};
    const userProps = Object.keys(props).filter((k) => !isSession || k !== "sessionId");
    if (userProps.length === 0) return null;
    return rpcMethodToClassName(method.rpcMethod) + "Params";
}

/** True if the method's params schema contains a "sessionId" property */
function methodHasSessionId(method: RpcMethodNode): boolean {
    const params = resolveMethodParamsSchema(method);
    return !!params?.properties && "sessionId" in params.properties;
}

/** True if the method's params object may be omitted entirely */
function methodParamsAreOptional(method: RpcMethodNode): boolean {
    const params = resolveRef(method.params ?? undefined);
    return !!params && typeof params === "object" && hasOmissionSentinel(params);
}

/**
 * Generate the Java source for a single method in a wrapper API class.
 * Returns the Java source lines and whether an ObjectMapper is required.
 */
export function generateApiMethod(
    key: string,
    method: RpcMethodNode,
    isSession: boolean,
    sessionIdExpr: string
): { lines: string[]; needsMapper: boolean; needsExperimentalImport: boolean; legacyRequestClass?: string } {
    const resultClass = wrapperResultClassName(method);
    const paramsClass = wrapperParamsClassName(method, isSession);
    const hasSessionId = methodHasSessionId(method);
    const hasExtraParams = paramsClass !== null;
    const paramsOptional = hasExtraParams && methodParamsAreOptional(method);
    const resultAllowsNull = methodResultAllowsNull(method);
    // Supervised-participant host operations are not owner-client APIs. Keep this
    // scoped to hosting rather than changing unrelated existing Java API exposure.
    const access = method.visibility === "internal" && method.rpcMethod.startsWith("host.") ? "" : "public ";
    let needsMapper = false;

    const lines: string[] = [];

    // Javadoc
    const description = (method.params as JSONSchema7 | null)?.description
        ?? (method.result as JSONSchema7 | null)?.description
        ?? `Invokes {@code ${method.rpcMethod}}.`;
    const pushJavadoc = (extraLines: string[] = [], includeSessionIdNote = true): void => {
        lines.push(`    /**`);
        lines.push(`     * ${description}`);
        if (includeSessionIdNote && isSession && hasExtraParams && hasSessionId) {
            lines.push(`     * <p>`);
            lines.push(`     * Note: the {@code sessionId} field in the params record is overridden`);
            lines.push(`     * by the session-scoped wrapper; any value provided is ignored.`);
        }
        lines.push(...extraLines);
        if (resultAllowsNull) {
            lines.push(`     *`);
            lines.push(`     * @return a future that completes with the {@code ${resultClass}} value,`);
            lines.push(`     *     or {@code null} when the result is absent. Callers must handle the`);
            lines.push(`     *     {@code null} completion value.`);
        }
        if (method.stability === "experimental") {
            lines.push(`     *`);
            lines.push(`     * @apiNote This method is experimental and may change in a future version.`);
        }
        lines.push(`     * @since 1.0.0`);
        lines.push(`     */`);
        if (method.deprecated) {
            lines.push(`    @Deprecated`);
        }
        if (method.stability === "experimental") {
            lines.push(`    @CopilotExperimental`);
        }
    };

    if (paramsOptional) {
        pushJavadoc([`     * <p>`, `     * Invokes the method with no params, applying the runtime defaults.`], false);
        lines.push(`    ${access}CompletableFuture<${resultClass}> ${key}() {`);
        lines.push(`        return ${key}(null);`);
        lines.push(`    }`);
        lines.push(``);
    }

    pushJavadoc();

    // Signature
    if (hasExtraParams) {
        lines.push(`    ${access}CompletableFuture<${resultClass}> ${key}(${paramsClass} params) {`);
    } else {
        lines.push(`    ${access}CompletableFuture<${resultClass}> ${key}() {`);
    }

    // Body
    if (isSession) {
        if (hasExtraParams) {
            // Merge sessionId into the params using Jackson ObjectNode
            needsMapper = true;
            const paramsNode = paramsOptional
                ? `params == null ? MAPPER.createObjectNode() : MAPPER.valueToTree(params)`
                : `MAPPER.valueToTree(params)`;
            lines.push(`        com.fasterxml.jackson.databind.node.ObjectNode _p = ${paramsNode};`);
            lines.push(`        _p.put("sessionId", ${sessionIdExpr});`);
            lines.push(`        return caller.invoke("${method.rpcMethod}", _p, ${wrapperResultTypeExpression(resultClass)});`);
        } else if (hasSessionId) {
            lines.push(`        return caller.invoke("${method.rpcMethod}", java.util.Map.of("sessionId", ${sessionIdExpr}), ${wrapperResultTypeExpression(resultClass)});`);
        } else {
            lines.push(`        return caller.invoke("${method.rpcMethod}", java.util.Map.of(), ${wrapperResultTypeExpression(resultClass)});`);
        }
    } else {
        // Server-side: pass params directly (or empty map if no params)
        if (hasExtraParams) {
            const paramsArg = paramsOptional ? `params == null ? java.util.Map.of() : params` : `params`;
            lines.push(`        return caller.invoke("${method.rpcMethod}", ${paramsArg}, ${wrapperResultTypeExpression(resultClass)});`);
        } else {
            lines.push(`        return caller.invoke("${method.rpcMethod}", java.util.Map.of(), ${wrapperResultTypeExpression(resultClass)});`);
        }
    }

    lines.push(`    }`);
    lines.push(``);

    const legacy = hasExtraParams ? javaLegacyParameters(method, isSession ? "session" : "server") : undefined;
    if (legacy) {
        const requestClass = legacyRequestClassName(method);
        pushJavadoc([`     * <p>`, `     * Accepts the extensible request, including inputs added after the params record.`], false);
        lines.push(`    public CompletableFuture<${resultClass}> ${key}(${requestClass} request) {`);
        if (isSession) {
            needsMapper = true;
            lines.push(`        com.fasterxml.jackson.databind.node.ObjectNode _p = MAPPER.valueToTree(Objects.requireNonNull(request, "request"));`);
            lines.push(`        _p.put("sessionId", ${sessionIdExpr});`);
            lines.push(`        return caller.invoke("${method.rpcMethod}", _p, ${wrapperResultTypeExpression(resultClass)});`);
        } else {
            lines.push(`        return caller.invoke("${method.rpcMethod}", Objects.requireNonNull(request, "request"), ${wrapperResultTypeExpression(resultClass)});`);
        }
        lines.push(`    }`);
        lines.push(``);
    }

    return { lines, needsMapper, needsExperimentalImport: method.stability === "experimental", legacyRequestClass: legacy ? legacyRequestClassName(method) : undefined };
}

/**
 * Generate a Java source file for a single namespace API class.
 * Returns the generated class name and whether a mapper static field is needed.
 */
async function generateNamespaceApiFile(
    prefix: string,
    namespacePath: string[],
    tree: NamespaceTree,
    isSession: boolean,
    packageName: string,
    packageDir: string
): Promise<string> {
    const className = apiClassName(prefix, namespacePath);
    const sessionIdExpr = "this.sessionId";

    const classLines: string[] = [];
    const allImports = new Set<string>([
        "java.util.concurrent.CompletableFuture",
        "javax.annotation.processing.Generated",
    ]);
    let needsMapper = false;

    // Generate sub-namespace fields
    const subFields: string[] = [];
    const subInits: string[] = [];
    for (const [subKey, subTree] of tree.subspaces) {
        const subClass = apiClassName(prefix, [...namespacePath, subKey]);
        subFields.push(`    /** API methods for the {@code ${[...namespacePath, subKey].join(".")}} sub-namespace. */`);
        subFields.push(`    public final ${subClass} ${subKey};`);
        if (isSession) {
            subInits.push(`        this.${subKey} = new ${subClass}(caller, sessionId);`);
        } else {
            subInits.push(`        this.${subKey} = new ${subClass}(caller);`);
        }
        // Recursively generate sub-namespace files
        await generateNamespaceApiFile(prefix, [...namespacePath, subKey], subTree, isSession, packageName, packageDir);
    }

    // Collect result/param imports and generate methods
    const methodLines: string[] = [];
    for (const [key, method] of tree.methods) {
        const resultClass = wrapperResultClassName(method);
        const paramsClass = wrapperParamsClassName(method, isSession);
        addWrapperResultImports(resultClass, allImports, packageName);
        if (paramsClass) allImports.add(`${packageName}.${paramsClass}`);

        const { lines, needsMapper: nm, needsExperimentalImport, legacyRequestClass } = generateApiMethod(key, method, isSession, sessionIdExpr);
        methodLines.push(...lines);
        if (nm) needsMapper = true;
        if (needsExperimentalImport) allImports.add("com.github.copilot.CopilotExperimental");
        if (legacyRequestClass) allImports.add("java.util.Objects");
    }

    // Build class body
    const qualifiedNs = namespacePath.length > 0 ? namespacePath.join(".") : prefix.toLowerCase();
    classLines.push(COPYRIGHT);
    classLines.push(``);
    classLines.push(AUTO_GENERATED_HEADER);
    classLines.push(GENERATED_FROM_API);
    classLines.push(``);
    classLines.push(`package ${packageName};`);
    classLines.push(``);

    // Add imports (skip same-package imports)
    const sortedImports = [...allImports].filter(imp => !imp.startsWith(packageName + ".")).sort();
    for (const imp of sortedImports) {
        classLines.push(`import ${imp};`);
    }
    classLines.push(``);

    // Javadoc for class
    classLines.push(`/**`);
    classLines.push(` * API methods for the {@code ${qualifiedNs}} namespace.`);
    classLines.push(` *`);
    classLines.push(` * @since 1.0.0`);
    classLines.push(` */`);
    classLines.push(GENERATED_ANNOTATION);
    classLines.push(`public final class ${className} {`);
    classLines.push(``);
    if (needsMapper) {
        classLines.push(`    private static final com.fasterxml.jackson.databind.ObjectMapper MAPPER = RpcMapper.INSTANCE;`);
        classLines.push(``);
    }
    classLines.push(`    private final RpcCaller caller;`);
    if (isSession) {
        classLines.push(`    private final String sessionId;`);
    }

    // Sub-namespace fields
    if (subFields.length > 0) {
        classLines.push(``);
        classLines.push(...subFields);
    }

    // Constructor
    classLines.push(``);
    if (isSession) {
        classLines.push(`    /** @param caller the RPC transport function */`);
        classLines.push(`    ${className}(RpcCaller caller, String sessionId) {`);
        classLines.push(`        this.caller = caller;`);
        classLines.push(`        this.sessionId = sessionId;`);
    } else {
        classLines.push(`    /** @param caller the RPC transport function */`);
        classLines.push(`    ${className}(RpcCaller caller) {`);
        classLines.push(`        this.caller = caller;`);
    }
    for (const init of subInits) {
        classLines.push(init);
    }
    classLines.push(`    }`);
    classLines.push(``);

    // Methods
    classLines.push(...methodLines);

    classLines.push(`}`);
    classLines.push(``);

    await writeGeneratedFile(`${packageDir}/${className}.java`, classLines.join("\n"));
    return className;
}

/**
 * Generate ServerRpc.java or SessionRpc.java — the top-level wrapper class.
 */
async function generateRpcRootFile(
    sectionName: string, // "server" | "session"
    tree: NamespaceTree,
    isSession: boolean,
    packageName: string,
    packageDir: string
): Promise<void> {
    const prefix = sectionName === "server" ? "Server" : "Session";
    const rootClassName = prefix + "Rpc";
    const sessionIdExpr = "this.sessionId";

    const classLines: string[] = [];
    const allImports = new Set<string>([
        "java.util.concurrent.CompletableFuture",
        "javax.annotation.processing.Generated",
    ]);
    let needsMapper = false;

    // Sub-namespace fields and init lines
    const subFields: string[] = [];
    const subInits: string[] = [];
    for (const [nsKey, nsTree] of tree.subspaces) {
        const nsClass = apiClassName(prefix, [nsKey]);
        subFields.push(`    /** API methods for the {@code ${nsKey}} namespace. */`);
        subFields.push(`    public final ${nsClass} ${nsKey};`);
        if (isSession) {
            subInits.push(`        this.${nsKey} = new ${nsClass}(caller, sessionId);`);
        } else {
            subInits.push(`        this.${nsKey} = new ${nsClass}(caller);`);
        }
        // Generate the namespace API class file (recursively)
        await generateNamespaceApiFile(prefix, [nsKey], nsTree, isSession, packageName, packageDir);
    }

    // Collect result/param imports and generate top-level method bodies
    const methodLines: string[] = [];
    for (const [key, method] of tree.methods) {
        const resultClass = wrapperResultClassName(method);
        const paramsClass = wrapperParamsClassName(method, isSession);
        addWrapperResultImports(resultClass, allImports, packageName);
        if (paramsClass) allImports.add(`${packageName}.${paramsClass}`);

        const { lines, needsMapper: nm, needsExperimentalImport, legacyRequestClass } = generateApiMethod(key, method, isSession, sessionIdExpr);
        methodLines.push(...lines);
        if (nm) needsMapper = true;
        if (needsExperimentalImport) allImports.add("com.github.copilot.CopilotExperimental");
        if (legacyRequestClass) allImports.add("java.util.Objects");
    }

    // Build file content
    classLines.push(COPYRIGHT);
    classLines.push(``);
    classLines.push(AUTO_GENERATED_HEADER);
    classLines.push(GENERATED_FROM_API);
    classLines.push(``);
    classLines.push(`package ${packageName};`);
    classLines.push(``);

    const sortedImports = [...allImports].filter(imp => !imp.startsWith(packageName + ".")).sort();
    for (const imp of sortedImports) {
        classLines.push(`import ${imp};`);
    }
    classLines.push(``);

    classLines.push(`/**`);
    if (isSession) {
        classLines.push(` * Typed client for session-scoped RPC methods.`);
        classLines.push(` * <p>`);
        classLines.push(` * Provides strongly-typed access to all session-level API namespaces.`);
        classLines.push(` * The {@code sessionId} is injected automatically into every call.`);
        classLines.push(` * <p>`);
        classLines.push(` * Obtain an instance by calling {@code new SessionRpc(caller, sessionId)}.`);
    } else {
        classLines.push(` * Typed client for server-level RPC methods.`);
        classLines.push(` * <p>`);
        classLines.push(` * Provides strongly-typed access to all server-level API namespaces.`);
        classLines.push(` * <p>`);
        classLines.push(` * Obtain an instance by calling {@code new ServerRpc(caller)}.`);
    }
    classLines.push(` *`);
    classLines.push(` * @since 1.0.0`);
    classLines.push(` */`);
    classLines.push(GENERATED_ANNOTATION);
    classLines.push(`public final class ${rootClassName} {`);
    classLines.push(``);
    if (needsMapper) {
        classLines.push(`    private static final com.fasterxml.jackson.databind.ObjectMapper MAPPER = RpcMapper.INSTANCE;`);
        classLines.push(``);
    }
    classLines.push(`    private final RpcCaller caller;`);
    if (isSession) {
        classLines.push(`    private final String sessionId;`);
    }
    if (subFields.length > 0) {
        classLines.push(``);
        classLines.push(...subFields);
    }
    classLines.push(``);

    // Constructor
    if (isSession) {
        classLines.push(`    /**`);
        classLines.push(`     * Creates a new session RPC client.`);
        classLines.push(`     *`);
        classLines.push(`     * @param caller    the RPC transport function (e.g., {@code jsonRpcClient::invoke})`);
        classLines.push(`     * @param sessionId the session ID to inject into every request`);
        classLines.push(`     */`);
        classLines.push(`    public ${rootClassName}(RpcCaller caller, String sessionId) {`);
        classLines.push(`        this.caller = caller;`);
        classLines.push(`        this.sessionId = sessionId;`);
    } else {
        classLines.push(`    /**`);
        classLines.push(`     * Creates a new server RPC client.`);
        classLines.push(`     *`);
        classLines.push(`     * @param caller the RPC transport function (e.g., {@code jsonRpcClient::invoke})`);
        classLines.push(`     */`);
        classLines.push(`    public ${rootClassName}(RpcCaller caller) {`);
        classLines.push(`        this.caller = caller;`);
    }
    for (const init of subInits) {
        classLines.push(init);
    }
    classLines.push(`    }`);
    classLines.push(``);

    // Top-level methods
    classLines.push(...methodLines);

    classLines.push(`}`);
    classLines.push(``);

    await writeGeneratedFile(`${packageDir}/${rootClassName}.java`, classLines.join("\n"));
}

/** Generate the RpcCaller functional interface */
async function generateRpcCallerInterface(packageName: string, packageDir: string): Promise<void> {
    const lines: string[] = [];
    lines.push(COPYRIGHT);
    lines.push(``);
    lines.push(AUTO_GENERATED_HEADER);
    lines.push(GENERATED_FROM_API);
    lines.push(``);
    lines.push(`package ${packageName};`);
    lines.push(``);
    lines.push(`import com.fasterxml.jackson.databind.JavaType;`);
    lines.push(`import com.fasterxml.jackson.databind.JsonNode;`);
    lines.push(`import java.util.concurrent.CompletableFuture;`);
    lines.push(`import java.util.concurrent.CompletionException;`);
    lines.push(`import javax.annotation.processing.Generated;`);
    lines.push(``);
    lines.push(`/**`);
    lines.push(` * Interface for invoking JSON-RPC methods with typed responses.`);
    lines.push(` * <p>`);
    lines.push(` * Implementations delegate to the underlying transport layer`);
    lines.push(` * (e.g., a {@code JsonRpcClient} instance). A method reference is typically the clearest`);
    lines.push(` * way to adapt a generic {@code invoke} method to this interface:`);
    lines.push(` * <pre>{@code`);
    lines.push(` * RpcCaller caller = jsonRpcClient::invoke;`);
    lines.push(` * }</pre>`);
    lines.push(` *`);
    lines.push(` * @since 1.0.0`);
    lines.push(` */`);
    lines.push(GENERATED_ANNOTATION);
    lines.push(`public interface RpcCaller {`);
    lines.push(``);
    lines.push(`    /**`);
    lines.push(`     * Invokes a JSON-RPC method and returns a future for the typed response.`);
    lines.push(`     *`);
    lines.push(`     * @param <T>        the expected response type`);
    lines.push(`     * @param method     the JSON-RPC method name`);
    lines.push(`     * @param params     the request parameters (may be a {@code Map}, DTO record, or {@code JsonNode})`);
    lines.push(`     * @param resultType the {@link Class} of the expected response type`);
    lines.push(`     * @return a {@link CompletableFuture} that completes with the deserialized result`);
    lines.push(`     */`);
    lines.push(`    <T> CompletableFuture<T> invoke(String method, Object params, Class<T> resultType);`);
    lines.push(``);
    lines.push(`    /**`);
    lines.push(`     * Invokes a JSON-RPC method and returns a future for the typed response.`);
    lines.push(`     *`);
    lines.push(`     * @param <T>        the expected response type`);
    lines.push(`     * @param method     the JSON-RPC method name`);
    lines.push(`     * @param params     the request parameters (may be a {@code Map}, DTO record, or {@code JsonNode})`);
    lines.push(`     * @param resultType the Jackson {@link JavaType} of the expected response type`);
    lines.push(`     * @return a {@link CompletableFuture} that completes with the deserialized result`);
    lines.push(`     */`);
    lines.push(`    default <T> CompletableFuture<T> invoke(String method, Object params, JavaType resultType) {`);
    lines.push(`        if (resultType.hasRawClass(Void.class) || resultType.hasRawClass(Void.TYPE)) {`);
    lines.push(`            return invoke(method, params, Void.class).thenApply(ignored -> null);`);
    lines.push(`        }`);
    lines.push(`        return invoke(method, params, JsonNode.class).thenApply(result -> {`);
    lines.push(`            try {`);
    lines.push(`                return RpcMapper.INSTANCE.readerFor(resultType).readValue(result);`);
    lines.push(`            } catch (java.io.IOException e) {`);
    lines.push(`                throw new CompletionException(e);`);
    lines.push(`            }`);
    lines.push(`        });`);
    lines.push(`    }`);
    lines.push(`}`);
    lines.push(``);

    await writeGeneratedFile(`${packageDir}/RpcCaller.java`, lines.join("\n"));
}

/**
 * Generate RpcMapper.java — a package-private holder for the shared ObjectMapper used
 * when merging sessionId into session API call params.  All session API classes that
 * need an ObjectMapper reference this single instance instead of instantiating their own.
 */
async function generateRpcMapperClass(packageName: string, packageDir: string): Promise<void> {
    const lines: string[] = [];
    lines.push(COPYRIGHT);
    lines.push(``);
    lines.push(AUTO_GENERATED_HEADER);
    lines.push(GENERATED_FROM_API);
    lines.push(``);
    lines.push(`package ${packageName};`);
    lines.push(``);
    lines.push(`import javax.annotation.processing.Generated;`);
    lines.push(``);
    lines.push(`/**`);
    lines.push(` * Package-private holder for the shared {@link com.fasterxml.jackson.databind.ObjectMapper}`);
    lines.push(` * used by session API classes when merging {@code sessionId} into call parameters.`);
    lines.push(` * <p>`);
    lines.push(` * {@link com.fasterxml.jackson.databind.ObjectMapper} is thread-safe and expensive to`);
    lines.push(` * instantiate, so a single shared instance is used across all generated API classes.`);
    lines.push(` * The configuration mirrors {@code JsonRpcClient}'s mapper (JavaTimeModule, lenient`);
    lines.push(` * unknown-property handling, ISO date format, NON_NULL inclusion).`);
    lines.push(` *`);
    lines.push(` * @since 1.0.0`);
    lines.push(` */`);
    lines.push(GENERATED_ANNOTATION);
    lines.push(`final class RpcMapper {`);
    lines.push(``);
    lines.push(`    static final com.fasterxml.jackson.databind.ObjectMapper INSTANCE = createMapper();`);
    lines.push(``);
    lines.push(`    private static com.fasterxml.jackson.databind.ObjectMapper createMapper() {`);
    lines.push(`        com.fasterxml.jackson.databind.ObjectMapper mapper = new com.fasterxml.jackson.databind.ObjectMapper();`);
    lines.push(`        mapper.registerModule(new com.fasterxml.jackson.datatype.jsr310.JavaTimeModule());`);
    lines.push(`        mapper.configure(com.fasterxml.jackson.databind.DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);`);
    lines.push(`        mapper.configure(com.fasterxml.jackson.databind.SerializationFeature.WRITE_DATES_AS_TIMESTAMPS, false);`);
    lines.push(`        mapper.setDefaultPropertyInclusion(com.fasterxml.jackson.annotation.JsonInclude.Include.NON_NULL);`);
    lines.push(`        return mapper;`);
    lines.push(`    }`);
    lines.push(``);
    lines.push(`    private RpcMapper() {}`);
    lines.push(`}`);
    lines.push(``);

    await writeGeneratedFile(`${packageDir}/RpcMapper.java`, lines.join("\n"));
}

/** Main entry point for RPC wrapper generation */
async function generateRpcWrappers(schemaPath: string): Promise<void> {
    console.log("\n🔧 Generating RPC wrapper classes...");

    const schemaContent = await fs.readFile(schemaPath, "utf-8");
    await emitRpcWrappers(normalizeSchemaBrandCasing(JSON.parse(schemaContent)) as RpcSchema);
    console.log(`✅ RPC wrapper classes generated`);
}

/** Render the RPC wrapper classes in memory. */
export async function renderRpcWrappers(schema: RpcSchema): Promise<Map<string, string>> {
    if (pendingOutput) throw new Error("Concurrent Java RPC wrapper generation is not supported.");
    const files = new Map<string, string>();
    pendingOutput = files;
    try {
        await emitRpcWrappers(schema);
        return files;
    } finally {
        pendingOutput = undefined;
    }
}

async function emitRpcWrappers(schema: RpcSchema): Promise<void> {
    // Set module-level definitions for $ref resolution in wrapper helpers
    currentDefinitions = (schema.definitions ?? {}) as Record<string, JSONSchema7>;

    const packageName = "com.github.copilot.generated.rpc";
    const packageDir = `sdk/src/generated/java/com/github/copilot/generated/rpc`;

    // RpcCaller interface and shared ObjectMapper holder
    await generateRpcCallerInterface(packageName, packageDir);
    await generateRpcMapperClass(packageName, packageDir);

    // Server-side wrappers
    if (schema.server) {
        const serverTree = buildNamespaceTree(schema.server);
        await generateRpcRootFile("server", serverTree, false, packageName, packageDir);
    }

    // Session-side wrappers
    if (schema.session) {
        const sessionTree = buildNamespaceTree(schema.session);
        await generateRpcRootFile("session", sessionTree, true, packageName, packageDir);
    }
}

// ── Package-info generation ──────────────────────────────────────────────────

async function generateGeneratedPackageInfo(packageDir: string): Promise<void> {
    const lines: string[] = [];
    lines.push(COPYRIGHT);
    lines.push("");
    lines.push(AUTO_GENERATED_HEADER);
    lines.push(GENERATED_FROM_SESSION_EVENTS);
    lines.push("");
    lines.push(`/**`);
    lines.push(` * Auto-generated session event types for the GitHub Copilot SDK.`);
    lines.push(` *`);
    lines.push(` * <p>`);
    lines.push(` * This package contains Java classes generated from the Copilot CLI's`);
    lines.push(` * {@code session-events.schema.json}. Each event type corresponds to a`);
    lines.push(` * notification emitted during a {@link com.github.copilot.CopilotSession}`);
    lines.push(` * interaction.`);
    lines.push(` *`);
    lines.push(` * <h2>Key Classes</h2>`);
    lines.push(` * <ul>`);
    lines.push(` * <li>{@link com.github.copilot.generated.SessionEvent} - Abstract sealed base`);
    lines.push(` * class for all session events. Deserialized polymorphically via the`);
    lines.push(` * {@code type} discriminator.</li>`);
    lines.push(` * <li>{@link com.github.copilot.generated.UnknownSessionEvent} - Fallback for`);
    lines.push(` * event types not yet known to this SDK version, preserving forward`);
    lines.push(` * compatibility.</li>`);
    lines.push(` * </ul>`);
    lines.push(` *`);
    lines.push(` * <h2>Example Usage</h2>`);
    lines.push(` *`);
    lines.push(` * <pre>{@code`);
    lines.push(` * session.on(AssistantMessageEvent.class, msg -> {`);
    lines.push(` *     System.out.println(msg.getData().content());`);
    lines.push(` * });`);
    lines.push(` * }</pre>`);
    lines.push(` *`);
    lines.push(` * <h2>Related Packages</h2>`);
    lines.push(` * <ul>`);
    lines.push(` * <li>{@link com.github.copilot} - Core SDK classes</li>`);
    lines.push(` * <li>{@link com.github.copilot.generated.rpc} - Auto-generated RPC`);
    lines.push(` * parameter and result types</li>`);
    lines.push(` * </ul>`);
    lines.push(` *`);
    lines.push(` * @see com.github.copilot.CopilotSession`);
    lines.push(` * @see com.github.copilot.generated.SessionEvent`);
    lines.push(` */`);
    lines.push(`package com.github.copilot.generated;`);
    lines.push("");

    await writeGeneratedFile(`${packageDir}/package-info.java`, lines.join("\n"));
}

async function generateRpcPackageInfo(packageDir: string): Promise<void> {
    const lines: string[] = [];
    lines.push(COPYRIGHT);
    lines.push("");
    lines.push(AUTO_GENERATED_HEADER);
    lines.push(GENERATED_FROM_API);
    lines.push("");
    lines.push(`/**`);
    lines.push(` * Auto-generated RPC parameter and result types for the GitHub Copilot SDK.`);
    lines.push(` *`);
    lines.push(` * <p>`);
    lines.push(` * This package contains Java records and classes generated from the Copilot`);
    lines.push(` * CLI's {@code api.schema.json}. These types represent the request parameters`);
    lines.push(` * and response payloads for all JSON-RPC methods exposed by the CLI.`);
    lines.push(` *`);
    lines.push(` * <h2>Key Classes</h2>`);
    lines.push(` * <ul>`);
    lines.push(` * <li>{@link com.github.copilot.generated.rpc.RpcCaller} - Functional interface`);
    lines.push(` * for invoking JSON-RPC methods with typed responses.</li>`);
    lines.push(` * <li>{@link com.github.copilot.generated.rpc.ServerRpc} - Typed client for`);
    lines.push(` * server-level RPC methods (session management, model listing, etc.).</li>`);
    lines.push(` * <li>{@link com.github.copilot.generated.rpc.SessionRpc} - Typed client for`);
    lines.push(` * session-scoped RPC methods (send messages, manage tools, etc.). Automatically`);
    lines.push(` * injects the {@code sessionId} into every call.</li>`);
    lines.push(` * </ul>`);
    lines.push(` *`);
    lines.push(` * <h2>Related Packages</h2>`);
    lines.push(` * <ul>`);
    lines.push(` * <li>{@link com.github.copilot} - Core SDK classes</li>`);
    lines.push(` * <li>{@link com.github.copilot.generated} - Auto-generated session event`);
    lines.push(` * types</li>`);
    lines.push(` * </ul>`);
    lines.push(` *`);
    lines.push(` * @see com.github.copilot.CopilotClient`);
    lines.push(` * @see com.github.copilot.generated.rpc.ServerRpc`);
    lines.push(` * @see com.github.copilot.generated.rpc.SessionRpc`);
    lines.push(` */`);
    lines.push(`package com.github.copilot.generated.rpc;`);
    lines.push("");

    await writeGeneratedFile(`${packageDir}/package-info.java`, lines.join("\n"));
}

// ── Main entry point ──────────────────────────────────────────────────────────

async function main(): Promise<void> {
    console.log("🚀 Java SDK code generator");
    console.log("============================");

    const sessionEventsSchemaPath = await getSessionEventsSchemaPath();
    console.log(`📄 Session events schema: ${sessionEventsSchemaPath}`);
    const apiSchemaPath = await getApiSchemaPath();
    console.log(`📄 API schema: ${apiSchemaPath}`);

    // Preserve the previous output on schema/ABI validation failures.
    const files = new Map<string, string>();
    pendingOutput = files;
    try {
        await generateSessionEvents(sessionEventsSchemaPath);
        await generateRpcTypes(apiSchemaPath);
        await generateRpcWrappers(apiSchemaPath);

        const generatedPkgDir = `sdk/src/generated/java/com/github/copilot/generated`;
        const rpcPkgDir = `sdk/src/generated/java/com/github/copilot/generated/rpc`;
        await generateGeneratedPackageInfo(generatedPkgDir);
        await generateRpcPackageInfo(rpcPkgDir);
    } finally {
        pendingOutput = undefined;
    }

    const generatedOutputDir = path.join(OUTPUT_ROOT, "sdk/src/generated/java/com/github/copilot/generated");
    console.log(`🧹 Cleaning output directory: ${generatedOutputDir}`);
    await fs.rm(generatedOutputDir, { recursive: true, force: true });
    await fs.mkdir(generatedOutputDir, { recursive: true });
    for (const [file, content] of files) await writeGeneratedFile(file, content);

    console.log("\n✅ Java code generation complete!");
}

export function isMainModule(entrypoint: string | undefined, modulePath: string): boolean {
    return !!entrypoint &&
        realpathSync(path.resolve(entrypoint)) === realpathSync(modulePath);
}

if (isMainModule(process.argv[1], __filename)) {
    main().catch((err) => {
        console.error("❌ Code generation failed:", err);
        process.exit(1);
    });
}