/*
 * Copyright 2022-2026 Revetware LLC.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.soklet;

import com.soklet.annotation.DELETE;
import com.soklet.annotation.GET;
import com.soklet.annotation.HEAD;
import com.soklet.annotation.McpListResources;
import com.soklet.annotation.McpPrompt;
import com.soklet.annotation.McpResource;
import com.soklet.annotation.McpServerEndpoint;
import com.soklet.annotation.McpTool;
import com.soklet.annotation.OPTIONS;
import com.soklet.annotation.PATCH;
import com.soklet.annotation.POST;
import com.soklet.annotation.PUT;
import com.soklet.annotation.SseEventSource;
import org.jspecify.annotations.NonNull;

import javax.annotation.concurrent.NotThreadSafe;
import javax.annotation.processing.AbstractProcessor;
import javax.annotation.processing.Filer;
import javax.annotation.processing.FilerException;
import javax.annotation.processing.Messager;
import javax.annotation.processing.ProcessingEnvironment;
import javax.annotation.processing.RoundEnvironment;
import javax.lang.model.SourceVersion;
import javax.lang.model.element.AnnotationMirror;
import javax.lang.model.element.AnnotationValue;
import javax.lang.model.element.Element;
import javax.lang.model.element.ElementKind;
import javax.lang.model.element.ExecutableElement;
import javax.lang.model.element.Modifier;
import javax.lang.model.element.TypeElement;
import javax.lang.model.element.VariableElement;
import javax.lang.model.type.TypeMirror;
import javax.lang.model.util.Elements;
import javax.lang.model.util.Types;
import javax.tools.Diagnostic;
import javax.tools.FileObject;
import javax.tools.StandardLocation;
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.UncheckedIOException;
import java.io.Writer;
import java.lang.annotation.Annotation;
import java.lang.annotation.Repeatable;
import java.net.URI;
import java.nio.charset.StandardCharsets;
import java.nio.file.AtomicMoveNotSupportedException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.nio.file.StandardCopyOption;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Base64;
import java.util.Collections;
import java.util.Comparator;
import java.util.LinkedHashMap;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.Set;
import java.util.stream.Collectors;

/**
 * Soklet's standard Annotation Processor which is used to generate lookup tables of <em>Resource Method</em> definitions at compile time as well as prevent usage errors that are detectable by static analysis.
 * <p>
 * This Annotation Processor ensures <em>Resource Methods</em> annotated with {@link SseEventSource} are declared as returning an instance of {@link SseHandshakeResult}.
 * <p>
 * Your build system should ensure this Annotation Processor is available at compile time. Follow the instructions below to make your application conformant:
 * <p>
 * Using {@code javac} directly:
 * <pre>javac -parameters -processor com.soklet.SokletProcessor ...[rest of javac command elided]</pre>
 * Using <a href="https://maven.apache.org" target="_blank">Maven</a>:
 * <pre>{@code <plugin>
 *     <groupId>org.apache.maven.plugins</groupId>
 *     <artifactId>maven-compiler-plugin</artifactId>
 *     <version>...</version>
 *     <configuration>
 *         <release>...</release>
 *         <compilerArgs>
 *             <!-- Rest of args elided -->
 *             <arg>-parameters</arg>
 *             <arg>-processor</arg>
 *             <arg>com.soklet.SokletProcessor</arg>
 *         </compilerArgs>
 *     </configuration>
 * </plugin>}</pre>
 * Using <a href="https://gradle.org" target="_blank">Gradle</a>:
 * <pre>{@code def sokletVersion = "3.2.0" // (use your actual version)
 *
 * dependencies {
 *   // Soklet used by your code at compile/run time
 *   implementation "com.soklet:soklet:${sokletVersion}"
 *
 *   // Same artifact also provides the annotation processor
 *   annotationProcessor "com.soklet:soklet:${sokletVersion}"
 *
 *   // If tests also need processing (optional)
 *   testAnnotationProcessor "com.soklet:soklet:${sokletVersion}"
 * }}</pre>
 *
 * <p><strong>Incremental/IDE ("IntelliJ-safe") behavior</strong>
 * <ul>
 *   <li>Never rebuilds the global index from only the currently-compiled sources. It always merges with the prior index.</li>
 *   <li>Only removes stale entries for top-level types compiled in the current compiler invocation (touched types).</li>
 *   <li>Skips writing the index entirely if compilation errors are present, preventing clobbering a good index.</li>
 *   <li>Writes with originating elements (best-effort) so incremental build tools can track dependencies.</li>
 * </ul>
 *
 * <p><strong>Processor options</strong>
 * <ul>
 *   <li><code>-Asoklet.cacheMode=none|sidecar|persistent</code> (default: <code>sidecar</code>)</li>
 *   <li><code>-Asoklet.cacheDir=/path</code> (used only when cacheMode=persistent; required to enable persistent)</li>
 *   <li><code>-Asoklet.pruneDeleted=true|false</code> (default: false; generally not IDE-safe)</li>
 *   <li><code>-Asoklet.debug=true|false</code> (default: false)</li>
 * </ul>
 *
 * <p><strong>Important</strong>: This processor will never create a project-root <code>.soklet</code> directory by default.
 * Persistent caching is only enabled when <code>cacheMode=persistent</code> <em>and</em> <code>soklet.cacheDir</code> is set.
 *
 * @author <a href="https://www.revetkn.com">Mark Allen</a>
 */
@NotThreadSafe
public final class SokletProcessor extends AbstractProcessor {
        // ---- Options ------------------------------------------------------------

        private static final String PROCESSOR_OPTION_CACHE_MODE = "soklet.cacheMode";
        private static final String PROCESSOR_OPTION_CACHE_DIR = "soklet.cacheDir";
        private static final String PROCESSOR_OPTION_PRUNE_DELETED = "soklet.pruneDeleted";
        private static final String PROCESSOR_OPTION_DEBUG = "soklet.debug";

        private static final String PERSISTENT_CACHE_INDEX_DIR = "resource-methods";
        private static final String MCP_PERSISTENT_CACHE_INDEX_DIR = "mcp-endpoints";

        // ---- Index paths ---------------------------------------------------------

        static final String RESOURCE_METHOD_LOOKUP_TABLE_PATH = "META-INF/soklet/resource-method-lookup-table";
        static final String MCP_ENDPOINT_LOOKUP_TABLE_PATH = "META-INF/soklet/mcp-endpoint-lookup-table";
        private static final String OUTPUT_ROOT_MARKER_PATH = "META-INF/soklet/.soklet-output-root";

        private static final String SIDE_CAR_DIR_NAME = "soklet";
        private static final String SIDE_CAR_INDEX_FILENAME = "resource-method-lookup-table";
        private static final String MCP_SIDE_CAR_INDEX_FILENAME = "mcp-endpoint-lookup-table";

        // ---- JSR-269 services ----------------------------------------------------

        private Types types;
        private Elements elements;
        private Messager messager;
        private Filer filer;

        private boolean debugEnabled;
        private boolean pruneDeletedEnabled;
        private CacheMode cacheMode;

        // Cached mirrors resolved in init()
        private TypeMirror sseHandshakeResultType;   // com.soklet.SseHandshakeResult
        private TypeMirror mcpToolResultType;        // com.soklet.McpToolResult
        private TypeMirror mcpPromptResultType;      // com.soklet.McpPromptResult
        private TypeMirror mcpResourceContentsType;  // com.soklet.McpResourceContents
        private TypeMirror mcpListResourcesResultType; // com.soklet.McpListResourcesResult
        private TypeElement pathParameterElement;    // com.soklet.annotation.PathParameter
        private TypeElement mcpEndpointElement;      // com.soklet.McpEndpoint

        // Collected during this compilation invocation
        private final List<ResourceMethodDeclaration> collected = new ArrayList<>();
        private final List<McpEndpointDeclaration> collectedMcpEndpoints = new ArrayList<>();
        private final Set<String> touchedTopLevelBinaries = new LinkedHashSet<>();
        private boolean resourceMethodAmbiguityDetected;

        // ---- Supported annotations ----------------------------------------------

        private static final List<Class<? extends Annotation>> HTTP_AND_SSE_ANNOTATIONS = List.of(
                        GET.class, POST.class, PUT.class, PATCH.class, DELETE.class, HEAD.class, OPTIONS.class,
                        SseEventSource.class
        );
        private static final List<Class<? extends Annotation>> MCP_ANNOTATIONS = List.of(
                        McpServerEndpoint.class, McpTool.class, McpPrompt.class, McpResource.class, McpListResources.class
        );

        // ---- Cache modes ---------------------------------------------------------

        private enum CacheMode {
                NONE,       // Only CLASS_OUTPUT index. No sidecar/persistent. Lowest clutter, lowest resiliency.
                SIDECAR,    // CLASS_OUTPUT + sidecar (under the class output parent directory). Default.
                PERSISTENT  // CLASS_OUTPUT + sidecar + persistent (under soklet.cacheDir). Requires soklet.cacheDir.
        }

        @Override
        public synchronized void init(ProcessingEnvironment processingEnv) {
                super.init(processingEnv);
                this.types = processingEnv.getTypeUtils();
                this.elements = processingEnv.getElementUtils();
                this.messager = processingEnv.getMessager();
                this.filer = processingEnv.getFiler();

                this.debugEnabled = parseBooleanishOption(processingEnv.getOptions().get(PROCESSOR_OPTION_DEBUG));
                this.pruneDeletedEnabled = parseBooleanishOption(processingEnv.getOptions().get(PROCESSOR_OPTION_PRUNE_DELETED));
                this.cacheMode = parseCacheMode(processingEnv.getOptions().get(PROCESSOR_OPTION_CACHE_MODE));

                        TypeElement hr = elements.getTypeElement("com.soklet.SseHandshakeResult");
                        this.sseHandshakeResultType = (hr == null ? null : hr.asType());
                        TypeElement mcpToolResult = elements.getTypeElement("com.soklet.McpToolResult");
                        this.mcpToolResultType = (mcpToolResult == null ? null : mcpToolResult.asType());
                        TypeElement mcpPromptResult = elements.getTypeElement("com.soklet.McpPromptResult");
                        this.mcpPromptResultType = (mcpPromptResult == null ? null : mcpPromptResult.asType());
                        TypeElement mcpResourceContents = elements.getTypeElement("com.soklet.McpResourceContents");
                        this.mcpResourceContentsType = (mcpResourceContents == null ? null : mcpResourceContents.asType());
                        TypeElement mcpListResourcesResult = elements.getTypeElement("com.soklet.McpListResourcesResult");
                        this.mcpListResourcesResultType = (mcpListResourcesResult == null ? null : mcpListResourcesResult.asType());
                        this.pathParameterElement = elements.getTypeElement("com.soklet.annotation.PathParameter");
                        this.mcpEndpointElement = elements.getTypeElement("com.soklet.McpEndpoint");

                // If persistent mode was requested but cacheDir isn't configured, downgrade to SIDECAR.
                if (this.cacheMode == CacheMode.PERSISTENT && persistentCacheRoot() == null) {
                        debug("SokletProcessor: cacheMode=persistent requested but %s not set/invalid; falling back to sidecar.",
                                        PROCESSOR_OPTION_CACHE_DIR);
                        this.cacheMode = CacheMode.SIDECAR;
                }
        }

        @Override
        public Set<String> getSupportedAnnotationTypes() {
                Set<String> out = new LinkedHashSet<>();
                for (Class<? extends Annotation> c : HTTP_AND_SSE_ANNOTATIONS) {
                        out.add(c.getCanonicalName());
                        Class<? extends Annotation> container = findRepeatableContainer(c);
                        if (container != null) out.add(container.getCanonicalName());
                }
                for (Class<? extends Annotation> c : MCP_ANNOTATIONS)
                        out.add(c.getCanonicalName());
                return out;
        }

        @Override
        public SourceVersion getSupportedSourceVersion() {
                return SourceVersion.latestSupported();
        }

        @Override
        public Set<String> getSupportedOptions() {
                return new LinkedHashSet<>(List.of(
                                PROCESSOR_OPTION_CACHE_MODE,
                                PROCESSOR_OPTION_CACHE_DIR,
                                PROCESSOR_OPTION_PRUNE_DELETED,
                                PROCESSOR_OPTION_DEBUG
                ));
        }

        @Override
        public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
                // Track top-level types being compiled in this invocation.
                for (Element root : roundEnv.getRootElements()) {
                        if (root instanceof TypeElement te) {
                                String bin = elements.getBinaryName(te).toString();
                                touchedTopLevelBinaries.add(bin);
                        }
                }

                        // SSE-specific return type check
                        enforceSseReturnTypes(roundEnv);
                        enforceMcpReturnTypes(roundEnv);

                // Collect + validate
                collect(roundEnv, HttpMethod.GET, GET.class, false);
                collect(roundEnv, HttpMethod.POST, POST.class, false);
                collect(roundEnv, HttpMethod.PUT, PUT.class, false);
                collect(roundEnv, HttpMethod.PATCH, PATCH.class, false);
                collect(roundEnv, HttpMethod.DELETE, DELETE.class, false);
                collect(roundEnv, HttpMethod.HEAD, HEAD.class, false);
                collect(roundEnv, HttpMethod.OPTIONS, OPTIONS.class, false);
                collect(roundEnv, HttpMethod.GET, SseEventSource.class, true); // SSE as GET + flag
                collectMcpEndpoints(roundEnv);

                if (roundEnv.processingOver()) {
                        // Critical: don't overwrite a good index with a partial/failed compile.
                        if (roundEnv.errorRaised() || resourceMethodAmbiguityDetected) {
                                debug("SokletProcessor: compilation has errors; skipping index write to avoid clobbering.");
                                return false;
                        }
                        mergeAndWriteIndex(collected, touchedTopLevelBinaries);
                        mergeAndWriteMcpIndex(collectedMcpEndpoints, touchedTopLevelBinaries);
                }

                return false;
        }

        /**
         * Collects and validates each annotated method occurrence (repeatable-aware, without reflection).
         */
        private void collect(RoundEnvironment roundEnv,
                                                                                         HttpMethod httpMethod,
                                                                                         Class<? extends Annotation> baseAnnotation,
                                                                                         boolean sseEventSource) {

                TypeElement base = elements.getTypeElement(baseAnnotation.getCanonicalName());
                Class<? extends Annotation> containerClass = findRepeatableContainer(baseAnnotation);
                TypeElement container = containerClass == null ? null : elements.getTypeElement(containerClass.getCanonicalName());

                Set<Element> candidates = new LinkedHashSet<>();
                if (base != null) candidates.addAll(roundEnv.getElementsAnnotatedWith(base));
                if (container != null) candidates.addAll(roundEnv.getElementsAnnotatedWith(container));

                for (Element e : candidates) {
                        if (e.getKind() != ElementKind.METHOD) {
                                error(e, "Soklet: @%s can only be applied to methods.", baseAnnotation.getSimpleName());
                                continue;
                        }

                        ExecutableElement method = (ExecutableElement) e;
                        TypeElement owner = (TypeElement) method.getEnclosingElement();

                        boolean isPublic = method.getModifiers().contains(Modifier.PUBLIC);
                        boolean isStatic = method.getModifiers().contains(Modifier.STATIC);

                        if (isStatic) error(method, "Soklet: Resource Method must not be static");
                        if (!isPublic) error(method, "Soklet: Resource Method must be public");

                        // Extract each occurrence as an AnnotationMirror (handles repeatable containers)
                        List<AnnotationMirror> occurrences = extractOccurrences(method, base, container);

                        for (AnnotationMirror annMirror : occurrences) {
                                String rawPath = readAnnotationStringMember(annMirror, "value");
                                if (rawPath == null || rawPath.isBlank()) {
                                        error(method, "Soklet: @%s must have a non-empty path value", baseAnnotation.getSimpleName());
                                        continue;
                                }

                                String path = normalizePath(rawPath);

                                ValidationResult vr = validatePathTemplate(method, path);
                                if (!vr.ok) continue;

                                ParamBindings pb = readPathParameterBindings(method);

                                // a) placeholders must be bound
                                for (String placeholder : vr.placeholders) {
                                        if (!pb.paramNames.contains(placeholder)) {
                                                String shown = vr.original.getOrDefault(placeholder, placeholder);
                                                error(method, "Resource Method path parameter {" + shown + "} not bound to a @PathParameter argument");
                                        }
                                }

                                // b) annotated params must exist in template
                                for (String annotated : pb.paramNames) {
                                        if (!vr.placeholders.contains(annotated)) {
                                                error(method, "No placeholder {" + annotated + "} present in resource path declaration");
                                        }
                                }

                                // Only collect if this method is otherwise valid
                                if (!pb.hadError && vr.ok && isPublic && !isStatic) {
                                        String className = elements.getBinaryName(owner).toString();
                                        String methodName = method.getSimpleName().toString();
                                        String[] paramTypes = method.getParameters().stream()
                                                        .map(p -> jvmTypeName(p.asType()))
                                                        .toArray(String[]::new);

                                        ResourceMethodDeclaration declaration = new ResourceMethodDeclaration(
                                                        httpMethod, path, className, methodName, paramTypes, sseEventSource
                                        );
                                        detectResourceMethodAmbiguity(method, declaration);
                                        collected.add(declaration);
                                }
                        }
                }
        }

        private List<AnnotationMirror> extractOccurrences(ExecutableElement method, TypeElement base, TypeElement container) {
                List<AnnotationMirror> out = new ArrayList<>();

                for (AnnotationMirror am : method.getAnnotationMirrors()) {
                        if (base != null && isAnnotationType(am, base)) {
                                out.add(am);
                        } else if (container != null && isAnnotationType(am, container)) {
                                Object v = readAnnotationMemberValue(am, "value");
                                if (v instanceof List<?> list) {
                                        for (Object o : list) {
                                                if (o instanceof AnnotationValue av) {
                                                        Object inner = av.getValue();
                                                        if (inner instanceof AnnotationMirror innerAm) {
                                                                out.add(innerAm);
                                                        }
                                                }
                                        }
                                }
                        }
                }

                return out;
        }

        // --- Helpers for parameter annotations ------------------------------------

        private static final class ParamBindings {
                final Set<String> paramNames;
                final boolean hadError;

                ParamBindings(Set<String> names, boolean hadError) {
                        this.paramNames = names;
                        this.hadError = hadError;
                }
        }

        private ParamBindings readPathParameterBindings(ExecutableElement method) {
                boolean hadError = false;
                Set<String> names = new LinkedHashSet<>();
                if (pathParameterElement == null) return new ParamBindings(names, false);

                for (VariableElement p : method.getParameters()) {
                        for (AnnotationMirror am : p.getAnnotationMirrors()) {
                                if (isAnnotationType(am, pathParameterElement)) {
                                        // 1) try explicit annotation member
                                        String name = readAnnotationStringMember(am, "name");
                                        // 2) default to the parameter's source name if missing/blank
                                        if (name == null || name.isBlank()) {
                                                name = p.getSimpleName().toString();
                                        }
                                        if (name != null && !name.isBlank()) {
                                                names.add(name);
                                        }
                                }
                        }
                }

                return new ParamBindings(names, hadError);
        }

        private static boolean isAnnotationType(AnnotationMirror am, TypeElement type) {
                return am.getAnnotationType().asElement().equals(type);
        }

        private static Object readAnnotationMemberValue(AnnotationMirror am, String member) {
                for (Map.Entry<? extends ExecutableElement, ? extends AnnotationValue> e : am.getElementValues().entrySet()) {
                        if (e.getKey().getSimpleName().contentEquals(member)) {
                                return e.getValue().getValue();
                        }
                }
                return null;
        }

        private static String readAnnotationStringMember(AnnotationMirror am, String member) {
                Object v = readAnnotationMemberValue(am, member);
                return (v == null) ? null : v.toString();
        }

        // --- Path parsing/validation ----------------------------------------------

        private static final class ValidationResult {
                final boolean ok;
                final Set<String> placeholders;       // normalized names (no trailing '*')
                final Map<String, String> original;   // normalized -> original token

                ValidationResult(boolean ok, Set<String> placeholders, Map<String, String> original) {
                        this.ok = ok;
                        this.placeholders = placeholders;
                        this.original = original;
                }
        }

        /**
         * Validates braces and duplicate placeholders (treating {name*} as a greedy/varargs placeholder whose
         * logical name is "name"). Duplicate detection is done on the normalized name (without trailing '*').
         */
        private ValidationResult validatePathTemplate(Element reportOn, String path) {
                if (path == null || path.isEmpty()) {
                        return new ValidationResult(false, Collections.emptySet(), Collections.emptyMap());
                }

                Set<String> names = new LinkedHashSet<>();
                Map<String, String> originalTokens = new LinkedHashMap<>();

                int i = 0;
                while (i < path.length()) {
                        char c = path.charAt(i);
                        if (c == '{') {
                                int close = path.indexOf('}', i + 1);
                                if (close < 0) {
                                        error(reportOn, "Soklet: Malformed resource path declaration (unbalanced braces)");
                                        return new ValidationResult(false, Collections.emptySet(), Collections.emptyMap());
                                }

                                String token = path.substring(i + 1, close);   // e.g., "id", "cssPath*"
                                if (token.isEmpty()) {
                                        error(reportOn, "Soklet: Malformed resource path declaration (unbalanced braces)");
                                        return new ValidationResult(false, Collections.emptySet(), Collections.emptyMap());
                                }

                                String normalized = normalizePlaceholder(token);
                                if (normalized.isEmpty()) {
                                        error(reportOn, "Soklet: Malformed resource path declaration (unbalanced braces)");
                                        return new ValidationResult(false, Collections.emptySet(), Collections.emptyMap());
                                }

                                if (!names.add(normalized)) {
                                        error(reportOn, "Soklet: Duplicate @PathParameter name: " + normalized);
                                }
                                originalTokens.putIfAbsent(normalized, token);

                                i = close + 1;
                        } else if (c == '}') {
                                error(reportOn, "Soklet: Malformed resource path declaration (unbalanced braces)");
                                return new ValidationResult(false, Collections.emptySet(), Collections.emptyMap());
                        } else {
                                i++;
                        }
                }

                return new ValidationResult(true, names, originalTokens);
        }

        private static String normalizePlaceholder(String token) {
                if (token.endsWith("*")) return token.substring(0, token.length() - 1);
                return token;
        }

        // --- MCP collection/validation --------------------------------------------

        private void collectMcpEndpoints(RoundEnvironment roundEnv) {
                TypeElement mcpServerEndpointType = elements.getTypeElement(McpServerEndpoint.class.getCanonicalName());

                if (mcpServerEndpointType != null) {
                        for (Element element : roundEnv.getElementsAnnotatedWith(mcpServerEndpointType)) {
                                if (element.getKind() != ElementKind.CLASS) {
                                        error(element, "Soklet: @%s can only be applied to classes.", McpServerEndpoint.class.getSimpleName());
                                        continue;
                                }

                                validateAndCollectMcpEndpoint((TypeElement) element);
                        }
                }

                validateMcpAnnotatedMethodsBelongToEndpoint(roundEnv, McpTool.class);
                validateMcpAnnotatedMethodsBelongToEndpoint(roundEnv, McpPrompt.class);
                validateMcpAnnotatedMethodsBelongToEndpoint(roundEnv, McpResource.class);
                validateMcpAnnotatedMethodsBelongToEndpoint(roundEnv, McpListResources.class);
        }

        private void validateAndCollectMcpEndpoint(TypeElement endpointType) {
                boolean valid = true;

                if (mcpEndpointElement == null || !types.isAssignable(endpointType.asType(), mcpEndpointElement.asType())) {
                        error(endpointType, "Soklet: Classes annotated with @%s must implement %s.",
                                        McpServerEndpoint.class.getSimpleName(), McpEndpoint.class.getSimpleName());
                        valid = false;
                }

                McpServerEndpoint endpoint = endpointType.getAnnotation(McpServerEndpoint.class);

                if (endpoint == null)
                        return;

                if (endpoint.path().isBlank()) {
                        error(endpointType, "Soklet: @%s path must be non-empty", McpServerEndpoint.class.getSimpleName());
                        valid = false;
                } else {
                        ValidationResult validationResult = validatePathTemplate(endpointType, normalizePath(endpoint.path()));
                        valid = valid && validationResult.ok;
                }

                if (endpoint.name().isBlank()) {
                        error(endpointType, "Soklet: @%s name must be non-empty", McpServerEndpoint.class.getSimpleName());
                        valid = false;
                }

                if (endpoint.version().isBlank()) {
                        error(endpointType, "Soklet: @%s version must be non-empty", McpServerEndpoint.class.getSimpleName());
                        valid = false;
                }

                String websiteUrl = endpoint.websiteUrl();
                if (websiteUrl != null && !websiteUrl.isBlank()
                                && !(websiteUrl.startsWith("https://") || websiteUrl.startsWith("http://"))) {
                        error(endpointType, "Soklet: @%s websiteUrl must start with http:// or https://", McpServerEndpoint.class.getSimpleName());
                        valid = false;
                }

                Set<String> toolNames = new LinkedHashSet<>();
                Set<String> promptNames = new LinkedHashSet<>();
                Set<String> resourceUris = new LinkedHashSet<>();
                Set<String> resourceNames = new LinkedHashSet<>();
                int resourceListMethodCount = 0;

                for (Element enclosedElement : endpointType.getEnclosedElements()) {
                        if (enclosedElement.getKind() != ElementKind.METHOD)
                                continue;

                        ExecutableElement method = (ExecutableElement) enclosedElement;

                        if (method.getAnnotation(McpTool.class) != null) {
                                if (!validateMcpAnnotatedMethod(method, McpTool.class.getSimpleName()))
                                        valid = false;

                                McpTool tool = method.getAnnotation(McpTool.class);

                                if (tool.name().isBlank()) {
                                        error(method, "Soklet: @%s name must be non-empty", McpTool.class.getSimpleName());
                                        valid = false;
                                } else if (!toolNames.add(tool.name())) {
                                        error(method, "Soklet: Duplicate MCP tool name '%s'", tool.name());
                                        valid = false;
                                }

                                if (tool.description().isBlank()) {
                                        error(method, "Soklet: @%s description must be non-empty", McpTool.class.getSimpleName());
                                        valid = false;
                                }
                        }

                        if (method.getAnnotation(McpPrompt.class) != null) {
                                if (!validateMcpAnnotatedMethod(method, McpPrompt.class.getSimpleName()))
                                        valid = false;

                                McpPrompt prompt = method.getAnnotation(McpPrompt.class);

                                if (prompt.name().isBlank()) {
                                        error(method, "Soklet: @%s name must be non-empty", McpPrompt.class.getSimpleName());
                                        valid = false;
                                } else if (!promptNames.add(prompt.name())) {
                                        error(method, "Soklet: Duplicate MCP prompt name '%s'", prompt.name());
                                        valid = false;
                                }

                                if (prompt.description().isBlank()) {
                                        error(method, "Soklet: @%s description must be non-empty", McpPrompt.class.getSimpleName());
                                        valid = false;
                                }
                        }

                        if (method.getAnnotation(McpResource.class) != null) {
                                if (!validateMcpAnnotatedMethod(method, McpResource.class.getSimpleName()))
                                        valid = false;

                                McpResource resource = method.getAnnotation(McpResource.class);

                                if (resource.uri().isBlank()) {
                                        error(method, "Soklet: @%s uri must be non-empty", McpResource.class.getSimpleName());
                                        valid = false;
                                } else {
                                        ValidationResult validationResult = validatePathTemplate(method, resource.uri());
                                        valid = valid && validationResult.ok;

                                        if (!resourceUris.add(resource.uri())) {
                                                error(method, "Soklet: Duplicate MCP resource URI '%s'", resource.uri());
                                                valid = false;
                                        }
                                }

                                if (resource.name().isBlank()) {
                                        error(method, "Soklet: @%s name must be non-empty", McpResource.class.getSimpleName());
                                        valid = false;
                                } else if (!resourceNames.add(resource.name())) {
                                        error(method, "Soklet: Duplicate MCP resource name '%s'", resource.name());
                                        valid = false;
                                }

                                if (resource.mimeType().isBlank()) {
                                        error(method, "Soklet: @%s mimeType must be non-empty", McpResource.class.getSimpleName());
                                        valid = false;
                                }
                        }

                        if (method.getAnnotation(McpListResources.class) != null) {
                                if (!validateMcpAnnotatedMethod(method, McpListResources.class.getSimpleName()))
                                        valid = false;

                                resourceListMethodCount++;
                        }
                }

                if (resourceListMethodCount > 1) {
                        error(endpointType, "Soklet: At most one @%s method may be declared on an MCP endpoint class.",
                                        McpListResources.class.getSimpleName());
                        valid = false;
                }

                if (valid)
                        collectedMcpEndpoints.add(new McpEndpointDeclaration(elements.getBinaryName(endpointType).toString()));
        }

        private void validateMcpAnnotatedMethodsBelongToEndpoint(RoundEnvironment roundEnv,
                                                                                                                                                                                                                 Class<? extends Annotation> annotationType) {
                TypeElement annotationElement = elements.getTypeElement(annotationType.getCanonicalName());

                if (annotationElement == null)
                        return;

                for (Element element : roundEnv.getElementsAnnotatedWith(annotationElement)) {
                        if (element.getKind() != ElementKind.METHOD) {
                                error(element, "Soklet: @%s can only be applied to methods.", annotationType.getSimpleName());
                                continue;
                        }

                        Element enclosingElement = element.getEnclosingElement();
                        if (!(enclosingElement instanceof TypeElement enclosingType)
                                        || enclosingType.getAnnotation(McpServerEndpoint.class) == null) {
                                error(element, "Soklet: Methods annotated with @%s must be declared on a class annotated with @%s.",
                                                annotationType.getSimpleName(), McpServerEndpoint.class.getSimpleName());
                        }
                }
        }

        private boolean validateMcpAnnotatedMethod(ExecutableElement method, String annotationSimpleName) {
                boolean valid = true;

                if (!method.getModifiers().contains(Modifier.PUBLIC)) {
                        error(method, "Soklet: Methods annotated with @%s must be public.", annotationSimpleName);
                        valid = false;
                }

                if (method.getModifiers().contains(Modifier.STATIC)) {
                        error(method, "Soklet: Methods annotated with @%s must not be static.", annotationSimpleName);
                        valid = false;
                }

                return valid;
        }

        // --- Existing utilities ----------------------------------------------------

        private static String normalizePath(String p) {
                if (p == null || p.isEmpty()) return "/";
                if (p.charAt(0) != '/') return "/" + p;
                return p;
        }

        private static Class<? extends Annotation> findRepeatableContainer(Class<? extends Annotation> base) {
                Repeatable repeatable = base.getAnnotation(Repeatable.class);
                return (repeatable == null) ? null : repeatable.value();
        }

        private String jvmTypeName(TypeMirror t) {
                switch (t.getKind()) {
                        case BOOLEAN:
                                return "boolean";
                        case BYTE:
                                return "byte";
                        case SHORT:
                                return "short";
                        case CHAR:
                                return "char";
                        case INT:
                                return "int";
                        case LONG:
                                return "long";
                        case FLOAT:
                                return "float";
                        case DOUBLE:
                                return "double";
                        case VOID:
                                return "void";
                        case ARRAY:
                                return "[" + jvmTypeDescriptor(((javax.lang.model.type.ArrayType) t).getComponentType());
                        case DECLARED:
                        default:
                                TypeMirror erasure = processingEnv.getTypeUtils().erasure(t);
                                Element el = processingEnv.getTypeUtils().asElement(erasure);
                                if (el instanceof TypeElement te) {
                                        return processingEnv.getElementUtils().getBinaryName(te).toString();
                                }
                                return erasure.toString();
                }
        }

        private String jvmTypeDescriptor(TypeMirror t) {
                switch (t.getKind()) {
                        case BOOLEAN:
                                return "Z";
                        case BYTE:
                                return "B";
                        case SHORT:
                                return "S";
                        case CHAR:
                                return "C";
                        case INT:
                                return "I";
                        case LONG:
                                return "J";
                        case FLOAT:
                                return "F";
                        case DOUBLE:
                                return "D";
                        case ARRAY:
                                return "[" + jvmTypeDescriptor(((javax.lang.model.type.ArrayType) t).getComponentType());
                        case DECLARED:
                        default:
                                TypeMirror erasure = processingEnv.getTypeUtils().erasure(t);
                                Element el = processingEnv.getTypeUtils().asElement(erasure);
                                if (el instanceof TypeElement te) {
                                        String bin = processingEnv.getElementUtils().getBinaryName(te).toString();
                                        return "L" + bin + ";";
                                }
                                return "Ljava/lang/Object;";
                }
        }

        // ---- SSE return-type validation ------------------------------------------

        private void enforceSseReturnTypes(RoundEnvironment roundEnv) {
                enforceAnnotatedReturnTypes(roundEnv, SseEventSource.class, sseHandshakeResultType, "SseHandshakeResult");
        }

        private void enforceMcpReturnTypes(RoundEnvironment roundEnv) {
                enforceAnnotatedReturnTypes(roundEnv, McpTool.class, mcpToolResultType, "McpToolResult");
                enforceAnnotatedReturnTypes(roundEnv, McpPrompt.class, mcpPromptResultType, "McpPromptResult");
                enforceAnnotatedReturnTypes(roundEnv, McpResource.class, mcpResourceContentsType, "McpResourceContents");
                enforceAnnotatedReturnTypes(roundEnv, McpListResources.class, mcpListResourcesResultType, "McpListResourcesResult");
        }

        private void enforceAnnotatedReturnTypes(RoundEnvironment roundEnv,
                                                                                                                                                                         Class<? extends Annotation> annotationType,
                                                                                                                                                                         TypeMirror expectedReturnType,
                                                                                                                                                                         String expectedReturnTypeName) {
                if (expectedReturnType == null)
                        return;

                TypeElement annotationElement = elements.getTypeElement(annotationType.getCanonicalName());
                if (annotationElement == null)
                        return;

                for (Element element : roundEnv.getElementsAnnotatedWith(annotationElement)) {
                        if (element.getKind() != ElementKind.METHOD) {
                                error(element, "@%s can only be applied to methods.", annotationType.getSimpleName());
                                continue;
                        }

                        ExecutableElement method = (ExecutableElement) element;
                        TypeMirror returnType = method.getReturnType();
                        boolean assignable = types.isAssignable(returnType, expectedReturnType);

                        if (!assignable) {
                                error(element,
                                                "Soklet: Methods annotated with @%s must specify a return type of %s (found: %s).",
                                                annotationType.getSimpleName(), expectedReturnTypeName, prettyType(returnType));
                        }
                }
        }

        private static String prettyType(TypeMirror t) {
                return (t == null ? "null" : t.toString());
        }

        // ---- Index read/merge/write ----------------------------------------------

        private void detectResourceMethodAmbiguity(@NonNull Element element,
                                                                                                                                                                                 @NonNull ResourceMethodDeclaration declaration) {
                for (ResourceMethodDeclaration existing : dedupeAndOrder(collected)) {
                        if (resourceMethodDeclarationsAmbiguous(existing, declaration)) {
                                resourceMethodAmbiguityDetected = true;
                                error(element, "Soklet: Ambiguous resource method declarations detected. %s overlaps %s",
                                                describeResourceMethodDeclaration(declaration), describeResourceMethodDeclaration(existing));
                        }
                }
        }

        private static boolean resourceMethodDeclarationsAmbiguous(@NonNull ResourceMethodDeclaration first,
                                                                                                                                                                                                                                                        @NonNull ResourceMethodDeclaration second) {
                if (generateKey(first).equals(generateKey(second)))
                        return false;

                ResourcePathDeclaration firstPath = ResourcePathDeclaration.fromPath(first.path());
                ResourcePathDeclaration secondPath = ResourcePathDeclaration.fromPath(second.path());
                ResourceMethodSpecificityKey firstKey = specificityKey(first, firstPath);
                ResourceMethodSpecificityKey secondKey = specificityKey(second, secondPath);

                return firstKey.equals(secondKey) && resourcePathDeclarationsOverlap(firstPath, secondPath);
        }

        @NonNull
        private static ResourceMethodSpecificityKey specificityKey(@NonNull ResourceMethodDeclaration declaration,
                                                                                                                                                                                                                                                 @NonNull ResourcePathDeclaration resourcePathDeclaration) {
                return new ResourceMethodSpecificityKey(
                                declaration.httpMethod(),
                                declaration.sseEventSource(),
                                resourcePathDeclaration.getVarargsComponent().isPresent(),
                                placeholderCount(resourcePathDeclaration),
                                literalCount(resourcePathDeclaration));
        }

        @NonNull
        private static String describeResourceMethodDeclaration(@NonNull ResourceMethodDeclaration declaration) {
                return String.format("%s %s %s -> %s#%s(%s)",
                                declaration.sseEventSource() ? "SSE" : "HTTP",
                                declaration.httpMethod().name(),
                                declaration.path(),
                                declaration.className(),
                                declaration.methodName(),
                                String.join(", ", declaration.parameterTypes()));
        }

        private static long placeholderCount(@NonNull ResourcePathDeclaration declaration) {
                return declaration.getComponents().stream()
                                .filter(component -> component.getType() == ResourcePathDeclaration.ComponentType.PLACEHOLDER)
                                .count();
        }

        private static long literalCount(@NonNull ResourcePathDeclaration declaration) {
                return declaration.getComponents().stream()
                                .filter(component -> component.getType() == ResourcePathDeclaration.ComponentType.LITERAL)
                                .count();
        }

        private static boolean resourcePathDeclarationsOverlap(@NonNull ResourcePathDeclaration first,
                                                                                                                                                                                                                                 @NonNull ResourcePathDeclaration second) {
                List<ResourcePathDeclaration.Component> firstComponents = first.getComponents();
                List<ResourcePathDeclaration.Component> secondComponents = second.getComponents();

                boolean firstHasVarargs = first.getVarargsComponent().isPresent();
                boolean secondHasVarargs = second.getVarargsComponent().isPresent();

                int firstPrefixLength = firstComponents.size() - (firstHasVarargs ? 1 : 0);
                int secondPrefixLength = secondComponents.size() - (secondHasVarargs ? 1 : 0);

                if (!firstHasVarargs && !secondHasVarargs) {
                        if (firstComponents.size() != secondComponents.size())
                                return false;

                        for (int i = 0; i < firstComponents.size(); i++)
                                if (!componentsCompatible(firstComponents.get(i), secondComponents.get(i)))
                                        return false;

                        return true;
                }

                if (firstHasVarargs && !secondHasVarargs) {
                        if (secondComponents.size() < firstPrefixLength)
                                return false;

                        for (int i = 0; i < firstPrefixLength; i++)
                                if (!componentsCompatible(firstComponents.get(i), secondComponents.get(i)))
                                        return false;

                        return true;
                }

                if (!firstHasVarargs) {
                        if (firstComponents.size() < secondPrefixLength)
                                return false;

                        for (int i = 0; i < secondPrefixLength; i++)
                                if (!componentsCompatible(firstComponents.get(i), secondComponents.get(i)))
                                        return false;

                        return true;
                }

                int minPrefixLength = Math.min(firstPrefixLength, secondPrefixLength);

                for (int i = 0; i < minPrefixLength; i++)
                        if (!componentsCompatible(firstComponents.get(i), secondComponents.get(i)))
                                return false;

                return true;
        }

        private static boolean componentsCompatible(ResourcePathDeclaration.@NonNull Component first,
                                                                                                                                                                                        ResourcePathDeclaration.@NonNull Component second) {
                if (first.getType() == ResourcePathDeclaration.ComponentType.LITERAL
                                && second.getType() == ResourcePathDeclaration.ComponentType.LITERAL)
                        return first.getValue().equals(second.getValue());

                return true;
        }

        private void mergeAndWriteIndex(List<ResourceMethodDeclaration> newlyCollected,
                                                                                                                                        Set<String> touchedTopLevelBinaries) {

                Path classOutputRoot = findClassOutputRoot();
                Path classOutputIndexPath = (classOutputRoot == null ? null : classOutputRoot.resolve(RESOURCE_METHOD_LOOKUP_TABLE_PATH));

                Path sideCarIndexPath = (cacheMode == CacheMode.NONE ? null : sideCarIndexPath(classOutputRoot));
                Path persistentIndexPath = (cacheMode == CacheMode.PERSISTENT ? persistentIndexPath(classOutputRoot) : null);

                debug("SokletProcessor: cacheMode=%s", cacheMode);
                debug("SokletProcessor: classOutputRoot=%s", classOutputRoot);
                debug("SokletProcessor: classOutputIndexPath=%s", classOutputIndexPath);
                debug("SokletProcessor: sidecarIndexPath=%s", sideCarIndexPath);
                debug("SokletProcessor: persistentIndexPath=%s", persistentIndexPath);
                debug("SokletProcessor: touchedTopLevels=%s", touchedTopLevelBinaries);

                // Always merge from ALL enabled sources. Never "fallback only if empty".
                Map<String, ResourceMethodDeclaration> merged = new LinkedHashMap<>();

                // Oldest/most durable first
                if (persistentIndexPath != null) readIndexFromPath(persistentIndexPath, merged);
                if (sideCarIndexPath != null) readIndexFromPath(sideCarIndexPath, merged);

                // Then current output dir (direct file access, if possible)
                if (classOutputIndexPath != null) readIndexFromPath(classOutputIndexPath, merged);

                // Then via filer (often works even if direct file paths don't)
                readIndexFromLocation(StandardLocation.CLASS_OUTPUT, merged);

                debug("SokletProcessor: mergedExistingIndexSize=%d", merged.size());

                // Remove stale entries for classes being recompiled now (top-level + nested)
                removeTouchedEntries(merged, touchedTopLevelBinaries);
                debug("SokletProcessor: afterRemovingTouched=%d", merged.size());

                // Add new entries
                for (ResourceMethodDeclaration r : dedupeAndOrder(newlyCollected)) {
                        merged.put(generateKey(r), r);
                }

                // Optional prune by classfile existence (NOT IDE-safe by default)
                if (pruneDeletedEnabled && classOutputRoot != null) {
                        merged.values().removeIf(r -> !classFileExistsInOutputRoot(classOutputRoot, r.className()));
                        debug("SokletProcessor: afterPruneDeleted=%d", merged.size());
                }

                List<ResourceMethodDeclaration> toWrite = new ArrayList<>(merged.values());
                toWrite.sort(Comparator
                                .comparing((ResourceMethodDeclaration r) -> r.httpMethod().name())
                                .thenComparing(ResourceMethodDeclaration::path)
                                .thenComparing(ResourceMethodDeclaration::className)
                                .thenComparing(ResourceMethodDeclaration::methodName));

                // Write CLASS_OUTPUT index (the real output)
                writeRoutesIndexResource(toWrite, classOutputIndexPath, touchedTopLevelBinaries, newlyCollected);

                // Write caches (best-effort)
                if (sideCarIndexPath != null) writeIndexFileAtomically(sideCarIndexPath, toWrite);
                if (persistentIndexPath != null) writeIndexFileAtomically(persistentIndexPath, toWrite);

                debug("SokletProcessor: wroteIndexSize=%d", toWrite.size());
        }

        private void mergeAndWriteMcpIndex(List<McpEndpointDeclaration> newlyCollected,
                                                                                                                                                 Set<String> touchedTopLevelBinaries) {
                Path classOutputRoot = findClassOutputRoot();
                Path classOutputIndexPath = (classOutputRoot == null ? null : classOutputRoot.resolve(MCP_ENDPOINT_LOOKUP_TABLE_PATH));
                Path sideCarIndexPath = (cacheMode == CacheMode.NONE ? null : sideCarMcpIndexPath(classOutputRoot));
                Path persistentIndexPath = (cacheMode == CacheMode.PERSISTENT ? persistentMcpIndexPath(classOutputRoot) : null);

                Map<String, McpEndpointDeclaration> merged = new LinkedHashMap<>();

                if (persistentIndexPath != null) readMcpIndexFromPath(persistentIndexPath, merged);
                if (sideCarIndexPath != null) readMcpIndexFromPath(sideCarIndexPath, merged);
                if (classOutputIndexPath != null) readMcpIndexFromPath(classOutputIndexPath, merged);
                readMcpIndexFromLocation(StandardLocation.CLASS_OUTPUT, merged);

                removeTouchedMcpEntries(merged, touchedTopLevelBinaries);

                for (McpEndpointDeclaration endpointDeclaration : dedupeAndOrderMcpEndpoints(newlyCollected))
                        merged.put(generateMcpEndpointKey(endpointDeclaration), endpointDeclaration);

                if (pruneDeletedEnabled && classOutputRoot != null)
                        merged.values().removeIf(endpointDeclaration -> !classFileExistsInOutputRoot(classOutputRoot, endpointDeclaration.className()));

                List<McpEndpointDeclaration> toWrite = dedupeAndOrderMcpEndpoints(new ArrayList<>(merged.values()));

                writeMcpIndexResource(toWrite, classOutputIndexPath, touchedTopLevelBinaries, newlyCollected);

                if (sideCarIndexPath != null) writeMcpIndexFileAtomically(sideCarIndexPath, toWrite);
                if (persistentIndexPath != null) writeMcpIndexFileAtomically(persistentIndexPath, toWrite);
        }

        private void removeTouchedEntries(Map<String, ResourceMethodDeclaration> merged,
                                                                                                                                                Set<String> touchedTopLevelBinaries) {
                if (touchedTopLevelBinaries == null || touchedTopLevelBinaries.isEmpty()) return;

                merged.values().removeIf(r -> {
                        String ownerBin = r.className();
                        for (String top : touchedTopLevelBinaries) {
                                if (ownerBin.equals(top) || ownerBin.startsWith(top + "$")) return true;
                        }
                        return false;
                });
        }

        private void removeTouchedMcpEntries(Map<String, McpEndpointDeclaration> merged,
                                                                                                                                                         Set<String> touchedTopLevelBinaries) {
                if (touchedTopLevelBinaries == null || touchedTopLevelBinaries.isEmpty()) return;

                merged.values().removeIf(endpointDeclaration -> {
                        String ownerBin = endpointDeclaration.className();
                        for (String top : touchedTopLevelBinaries) {
                                if (ownerBin.equals(top) || ownerBin.startsWith(top + "$")) return true;
                        }
                        return false;
                });
        }

        private boolean readIndexFromLocation(StandardLocation location, Map<String, ResourceMethodDeclaration> out) {
                try {
                        FileObject fo = filer.getResource(location, "", RESOURCE_METHOD_LOOKUP_TABLE_PATH);
                        try (BufferedReader reader = new BufferedReader(new InputStreamReader(fo.openInputStream(), StandardCharsets.UTF_8))) {
                                readIndexFromReader(reader, out);
                        }
                        return true;
                } catch (IOException ignored) {
                        return false;
                }
        }

        private boolean readMcpIndexFromLocation(StandardLocation location, Map<String, McpEndpointDeclaration> out) {
                try {
                        FileObject fo = filer.getResource(location, "", MCP_ENDPOINT_LOOKUP_TABLE_PATH);
                        try (BufferedReader reader = new BufferedReader(new InputStreamReader(fo.openInputStream(), StandardCharsets.UTF_8))) {
                                readMcpIndexFromReader(reader, out);
                        }
                        return true;
                } catch (IOException ignored) {
                        return false;
                }
        }

        private boolean readIndexFromPath(Path path, Map<String, ResourceMethodDeclaration> out) {
                if (path == null || !Files.isRegularFile(path)) return false;
                try (BufferedReader reader = Files.newBufferedReader(path, StandardCharsets.UTF_8)) {
                        readIndexFromReader(reader, out);
                        return true;
                } catch (IOException ignored) {
                        return false;
                }
        }

        private boolean readMcpIndexFromPath(Path path, Map<String, McpEndpointDeclaration> out) {
                if (path == null || !Files.isRegularFile(path)) return false;
                try (BufferedReader reader = Files.newBufferedReader(path, StandardCharsets.UTF_8)) {
                        readMcpIndexFromReader(reader, out);
                        return true;
                } catch (IOException ignored) {
                        return false;
                }
        }

        private void readIndexFromReader(BufferedReader reader, Map<String, ResourceMethodDeclaration> out) throws IOException {
                String line;
                while ((line = reader.readLine()) != null) {
                        line = line.trim();
                        if (line.isEmpty()) continue;
                        ResourceMethodDeclaration r = parseIndexLine(line);
                        if (r != null) out.put(generateKey(r), r);
                }
        }

        private void readMcpIndexFromReader(BufferedReader reader, Map<String, McpEndpointDeclaration> out) throws IOException {
                String line;
                while ((line = reader.readLine()) != null) {
                        line = line.trim();
                        if (line.isEmpty()) continue;
                        McpEndpointDeclaration endpointDeclaration = parseMcpIndexLine(line);
                        if (endpointDeclaration != null) out.put(generateMcpEndpointKey(endpointDeclaration), endpointDeclaration);
                }
        }

        private Path findClassOutputRoot() {
                // Try to read an existing marker file
                try {
                        FileObject fo = filer.getResource(StandardLocation.CLASS_OUTPUT, "", OUTPUT_ROOT_MARKER_PATH);
                        Path root = outputRootFromUri(fo.toUri(), OUTPUT_ROOT_MARKER_PATH);
                        if (root != null) return root;
                } catch (IOException ignored) {
                }

                // Create marker to discover root
                try {
                        FileObject fo = filer.createResource(StandardLocation.CLASS_OUTPUT, "", OUTPUT_ROOT_MARKER_PATH);
                        try (Writer w = fo.openWriter()) {
                                w.write("");
                        }
                        return outputRootFromUri(fo.toUri(), OUTPUT_ROOT_MARKER_PATH);
                } catch (IOException ignored) {
                        return null;
                }
        }

        private Path sideCarIndexPath(Path classOutputRoot) {
                if (classOutputRoot == null) return null;
                Path parent = classOutputRoot.getParent();
                if (parent == null) return null;
                String outputRootName = classOutputRoot.getFileName().toString();
                return parent.resolve(SIDE_CAR_DIR_NAME).resolve(outputRootName).resolve(SIDE_CAR_INDEX_FILENAME);
        }

        private Path persistentIndexPath(Path classOutputRoot) {
                if (classOutputRoot == null) return null;
                Path cacheRoot = persistentCacheRoot();
                if (cacheRoot == null) return null;

                String key = hashPath(classOutputRoot.toAbsolutePath().normalize().toString());
                return cacheRoot.resolve(PERSISTENT_CACHE_INDEX_DIR).resolve(key).resolve(SIDE_CAR_INDEX_FILENAME);
        }

        private Path sideCarMcpIndexPath(Path classOutputRoot) {
                if (classOutputRoot == null) return null;
                Path parent = classOutputRoot.getParent();
                if (parent == null) return null;
                String outputRootName = classOutputRoot.getFileName().toString();
                return parent.resolve(SIDE_CAR_DIR_NAME).resolve(outputRootName).resolve(MCP_SIDE_CAR_INDEX_FILENAME);
        }

        private Path persistentMcpIndexPath(Path classOutputRoot) {
                if (classOutputRoot == null) return null;
                Path cacheRoot = persistentCacheRoot();
                if (cacheRoot == null) return null;

                String key = hashPath(classOutputRoot.toAbsolutePath().normalize().toString());
                return cacheRoot.resolve(MCP_PERSISTENT_CACHE_INDEX_DIR).resolve(key).resolve(MCP_SIDE_CAR_INDEX_FILENAME);
        }

        /**
         * Persistent caching is only enabled when soklet.cacheDir is explicitly set.
         * This avoids writing project-root ".soklet" directories by default.
         */
        private Path persistentCacheRoot() {
                String override = processingEnv.getOptions().get(PROCESSOR_OPTION_CACHE_DIR);
                if (override == null || override.isBlank()) return null;
                try {
                        return Paths.get(override);
                } catch (RuntimeException ignored) {
                        return null;
                }
        }

        private boolean classFileExistsInOutputRoot(Path root, String binaryName) {
                if (root == null) return true;
                Path classFile = root.resolve(binaryName.replace('.', '/') + ".class");
                return Files.isRegularFile(classFile);
        }

        private Path outputRootFromUri(URI uri, String pathSuffix) {
                if (uri == null || !"file".equalsIgnoreCase(uri.getScheme())) return null;
                Path file = Paths.get(uri);
                int segments = countPathSegments(pathSuffix);
                Path root = file;
                for (int i = 0; i < segments; i++) {
                        root = root.getParent();
                        if (root == null) return null;
                }
                return root;
        }

        private ResourceMethodDeclaration parseIndexLine(String line) {
                try {
                        String[] parts = line.split("\\|", -1);
                        if (parts.length < 6) return null;

                        HttpMethod httpMethod = HttpMethod.valueOf(parts[0]);
                        Base64.Decoder dec = Base64.getDecoder();

                        String path = new String(dec.decode(parts[1]), StandardCharsets.UTF_8);
                        String className = new String(dec.decode(parts[2]), StandardCharsets.UTF_8);
                        String methodName = new String(dec.decode(parts[3]), StandardCharsets.UTF_8);
                        String paramsJoined = new String(dec.decode(parts[4]), StandardCharsets.UTF_8);
                        boolean sse = Boolean.parseBoolean(parts[5]);

                        String[] paramTypes;
                        if (paramsJoined.isEmpty()) {
                                paramTypes = new String[0];
                        } else {
                                List<String> tmp = Arrays.stream(paramsJoined.split(";"))
                                                .filter(s -> !s.isEmpty())
                                                .collect(Collectors.toList());
                                paramTypes = tmp.toArray(String[]::new);
                        }

                        return new ResourceMethodDeclaration(httpMethod, path, className, methodName, paramTypes, sse);
                } catch (Throwable t) {
                        return null;
                }
        }

        private McpEndpointDeclaration parseMcpIndexLine(String line) {
                try {
                        String className = new String(Base64.getDecoder().decode(line), StandardCharsets.UTF_8);
                        return new McpEndpointDeclaration(className);
                } catch (Throwable t) {
                        return null;
                }
        }

        /**
         * Writes the merged index to CLASS_OUTPUT.
         * Uses originating elements (best effort) so incremental build tools can track dependencies.
         *
         * <p>Fallback strategy if createResource fails:
         * <ol>
         *   <li>Try opening a writer on filer.getResource(...)</li>
         *   <li>Try direct filesystem write if classOutputIndexPath is available</li>
         * </ol>
         */
        private void writeRoutesIndexResource(List<ResourceMethodDeclaration> routes,
                                                                                                                                                                Path classOutputIndexPath,
                                                                                                                                                                Set<String> touchedTopLevelBinaries,
                                                                                                                                                                List<ResourceMethodDeclaration> newlyCollected) {
                Element[] origins = computeOriginatingElements(touchedTopLevelBinaries, newlyCollected);

                try {
                        FileObject fo = filer.createResource(StandardLocation.CLASS_OUTPUT, "", RESOURCE_METHOD_LOOKUP_TABLE_PATH, origins);
                        try (Writer w = fo.openWriter()) {
                                writeIndexToWriter(w, routes);
                        }
                        return;
                } catch (FilerException exists) {
                        // Try writing via getResource/openWriter
                        try {
                                FileObject fo = filer.getResource(StandardLocation.CLASS_OUTPUT, "", RESOURCE_METHOD_LOOKUP_TABLE_PATH);
                                try (Writer w = fo.openWriter()) {
                                        writeIndexToWriter(w, routes);
                                }
                                return;
                        } catch (IOException ignored) {
                                // Fall through to direct path write if available
                        }
                } catch (IOException e) {
                        // Fall through to direct path write if available
                        debug("SokletProcessor: filer.createResource/openWriter failed (%s); attempting direct write.", e);
                }

                // Direct path write (best effort)
                if (classOutputIndexPath != null) {
                        try {
                                writeIndexFileAtomicallyOrThrow(classOutputIndexPath, routes);
                                return;
                        } catch (IOException e) {
                                throw new UncheckedIOException("Failed to write " + RESOURCE_METHOD_LOOKUP_TABLE_PATH, e);
                        }
                }

                throw new UncheckedIOException("Failed to write " + RESOURCE_METHOD_LOOKUP_TABLE_PATH, new IOException("No writable CLASS_OUTPUT path available"));
        }

        private void writeMcpIndexResource(List<McpEndpointDeclaration> endpoints,
                                                                                                                                                 Path classOutputIndexPath,
                                                                                                                                                 Set<String> touchedTopLevelBinaries,
                                                                                                                                                 List<McpEndpointDeclaration> newlyCollected) {
                Element[] origins = computeMcpOriginatingElements(touchedTopLevelBinaries, newlyCollected);

                try {
                        FileObject fo = filer.createResource(StandardLocation.CLASS_OUTPUT, "", MCP_ENDPOINT_LOOKUP_TABLE_PATH, origins);
                        try (Writer w = fo.openWriter()) {
                                writeMcpIndexToWriter(w, endpoints);
                        }
                        return;
                } catch (FilerException exists) {
                        try {
                                FileObject fo = filer.getResource(StandardLocation.CLASS_OUTPUT, "", MCP_ENDPOINT_LOOKUP_TABLE_PATH);
                                try (Writer w = fo.openWriter()) {
                                        writeMcpIndexToWriter(w, endpoints);
                                }
                                return;
                        } catch (IOException ignored) {
                                // Fall through to direct path write if available
                        }
                } catch (IOException e) {
                        debug("SokletProcessor: filer.createResource/openWriter for MCP index failed (%s); attempting direct write.", e);
                }

                if (classOutputIndexPath != null) {
                        try {
                                writeMcpIndexFileAtomicallyOrThrow(classOutputIndexPath, endpoints);
                                return;
                        } catch (IOException e) {
                                throw new UncheckedIOException("Failed to write " + MCP_ENDPOINT_LOOKUP_TABLE_PATH, e);
                        }
                }

                throw new UncheckedIOException("Failed to write " + MCP_ENDPOINT_LOOKUP_TABLE_PATH, new IOException("No writable CLASS_OUTPUT path available"));
        }

        private Element[] computeOriginatingElements(Set<String> touchedTopLevelBinaries,
                                                                                                                                                                                         List<ResourceMethodDeclaration> newlyCollected) {
                Set<Element> origins = new LinkedHashSet<>();

                // Always include touched top-level types (these are definitely in this compilation)
                if (touchedTopLevelBinaries != null) {
                        for (String top : touchedTopLevelBinaries) {
                                TypeElement te = elements.getTypeElement(top);
                                if (te != null) origins.add(te);
                        }
                }

                // Also include owners of newly collected routes (top-level if possible)
                if (newlyCollected != null) {
                        for (ResourceMethodDeclaration r : newlyCollected) {
                                String bin = r.className();
                                int dollar = bin.indexOf('$');
                                String top = (dollar >= 0) ? bin.substring(0, dollar) : bin;

                                TypeElement te = elements.getTypeElement(top);
                                if (te != null) origins.add(te);
                        }
                }

                return origins.toArray(new Element[0]);
        }

        private Element[] computeMcpOriginatingElements(Set<String> touchedTopLevelBinaries,
                                                                                                                                                                                                        List<McpEndpointDeclaration> newlyCollected) {
                Set<Element> origins = new LinkedHashSet<>();

                if (touchedTopLevelBinaries != null) {
                        for (String top : touchedTopLevelBinaries) {
                                TypeElement te = elements.getTypeElement(top);
                                if (te != null) origins.add(te);
                        }
                }

                if (newlyCollected != null) {
                        for (McpEndpointDeclaration endpointDeclaration : newlyCollected) {
                                String bin = endpointDeclaration.className();
                                int dollar = bin.indexOf('$');
                                String top = (dollar >= 0) ? bin.substring(0, dollar) : bin;

                                TypeElement te = elements.getTypeElement(top);
                                if (te != null) origins.add(te);
                        }
                }

                return origins.toArray(new Element[0]);
        }

        private void writeIndexToWriter(Writer w, List<ResourceMethodDeclaration> routes) throws IOException {
                Base64.Encoder b64 = Base64.getEncoder();
                for (ResourceMethodDeclaration r : routes) {
                        String params = String.join(";", r.parameterTypes());
                        String line = String.join("|",
                                        r.httpMethod().name(),
                                        b64encode(b64, r.path()),
                                        b64encode(b64, r.className()),
                                        b64encode(b64, r.methodName()),
                                        b64encode(b64, params),
                                        Boolean.toString(r.sseEventSource())
                        );
                        w.write(line);
                        w.write('\n');
                }
        }

        private void writeMcpIndexToWriter(Writer w, List<McpEndpointDeclaration> endpoints) throws IOException {
                Base64.Encoder b64 = Base64.getEncoder();
                for (McpEndpointDeclaration endpointDeclaration : endpoints) {
                        w.write(b64encode(b64, endpointDeclaration.className()));
                        w.write('\n');
                }
        }

        /**
         * Best-effort atomic write. Failures are logged (if debug enabled) and ignored.
         */
        private void writeIndexFileAtomically(Path target, List<ResourceMethodDeclaration> routes) {
                if (target == null) return;
                try {
                        writeIndexFileAtomicallyOrThrow(target, routes);
                } catch (IOException e) {
                        debug("SokletProcessor: failed to write cache index %s (%s)", target, e);
                }
        }

        private void writeMcpIndexFileAtomically(Path target, List<McpEndpointDeclaration> endpoints) {
                if (target == null) return;
                try {
                        writeMcpIndexFileAtomicallyOrThrow(target, endpoints);
                } catch (IOException e) {
                        debug("SokletProcessor: failed to write MCP cache index %s (%s)", target, e);
                }
        }

        private void writeIndexFileAtomicallyOrThrow(Path target, List<ResourceMethodDeclaration> routes) throws IOException {
                Path parent = target.getParent();
                if (parent != null) Files.createDirectories(parent);

                // temp file in same dir so move is atomic on most filesystems
                Path tmp = Files.createTempFile(parent, target.getFileName().toString(), ".tmp");
                try (Writer w = Files.newBufferedWriter(tmp, StandardCharsets.UTF_8)) {
                        writeIndexToWriter(w, routes);
                }

                try {
                        Files.move(tmp, target, StandardCopyOption.REPLACE_EXISTING, StandardCopyOption.ATOMIC_MOVE);
                } catch (AtomicMoveNotSupportedException e) {
                        Files.move(tmp, target, StandardCopyOption.REPLACE_EXISTING);
                }
        }

        private void writeMcpIndexFileAtomicallyOrThrow(Path target, List<McpEndpointDeclaration> endpoints) throws IOException {
                Path parent = target.getParent();
                if (parent != null) Files.createDirectories(parent);

                Path tmp = Files.createTempFile(parent, target.getFileName().toString(), ".tmp");
                try (Writer w = Files.newBufferedWriter(tmp, StandardCharsets.UTF_8)) {
                        writeMcpIndexToWriter(w, endpoints);
                }

                try {
                        Files.move(tmp, target, StandardCopyOption.REPLACE_EXISTING, StandardCopyOption.ATOMIC_MOVE);
                } catch (AtomicMoveNotSupportedException e) {
                        Files.move(tmp, target, StandardCopyOption.REPLACE_EXISTING);
                }
        }

        private static String b64encode(Base64.Encoder enc, String s) {
                byte[] bytes = (s == null ? new byte[0] : s.getBytes(StandardCharsets.UTF_8));
                return enc.encodeToString(bytes);
        }

        // ---- Messaging ------------------------------------------------------------

        private void error(Element e, String fmt, Object... args) {
                messager.printMessage(Diagnostic.Kind.ERROR, String.format(fmt, args), e);
        }

        private void debug(String fmt, Object... args) {
                if (!debugEnabled) return;
                messager.printMessage(Diagnostic.Kind.NOTE, String.format(fmt, args));
        }

        // ---- Misc helpers ---------------------------------------------------------

        private static CacheMode parseCacheMode(String option) {
                if (option == null || option.isBlank()) return CacheMode.SIDECAR;

                String normalized = option.trim().toLowerCase(Locale.ROOT);
                switch (normalized) {
                        case "none":
                        case "off":
                        case "false":
                                return CacheMode.NONE;
                        case "sidecar":
                                return CacheMode.SIDECAR;
                        case "persistent":
                        case "persist":
                                return CacheMode.PERSISTENT;
                        default:
                                // Unknown -> default to sidecar for safety
                                return CacheMode.SIDECAR;
                }
        }

        private static boolean parseBooleanishOption(String option) {
                if (option == null) return false;
                String normalized = option.trim();
                if (normalized.isEmpty()) return false;
                return !"false".equalsIgnoreCase(normalized);
        }

        private static String hashPath(String input) {
                try {
                        MessageDigest digest = MessageDigest.getInstance("SHA-1");
                        byte[] bytes = digest.digest(input.getBytes(StandardCharsets.UTF_8));
                        return toHex(bytes);
                } catch (NoSuchAlgorithmException e) {
                        return Integer.toHexString(input.hashCode());
                }
        }

        private static String toHex(byte[] bytes) {
                char[] out = new char[bytes.length * 2];
                char[] digits = "0123456789abcdef".toCharArray();
                for (int i = 0; i < bytes.length; i++) {
                        int v = bytes[i] & 0xFF;
                        out[i * 2] = digits[v >>> 4];
                        out[i * 2 + 1] = digits[v & 0x0F];
                }
                return new String(out);
        }

        private static int countPathSegments(String path) {
                int count = 1;
                for (int i = 0; i < path.length(); i++) {
                        if (path.charAt(i) == '/') count++;
                }
                return count;
        }

        private static String generateKey(ResourceMethodDeclaration r) {
                return r.httpMethod().name() + "|" + r.path() + "|" + r.className() + "|" +
                                r.methodName() + "|" + String.join(";", r.parameterTypes()) + "|" +
                                r.sseEventSource();
        }

        private static String generateMcpEndpointKey(McpEndpointDeclaration endpointDeclaration) {
                return endpointDeclaration.className();
        }

        private static List<ResourceMethodDeclaration> dedupeAndOrder(List<ResourceMethodDeclaration> in) {
                Map<String, ResourceMethodDeclaration> byKey = new LinkedHashMap<>();
                for (ResourceMethodDeclaration r : in) byKey.putIfAbsent(generateKey(r), r);

                List<ResourceMethodDeclaration> out = new ArrayList<>(byKey.values());
                out.sort(Comparator
                                .comparing((ResourceMethodDeclaration r) -> r.httpMethod().name())
                                .thenComparing(ResourceMethodDeclaration::path)
                                .thenComparing(ResourceMethodDeclaration::className)
                                .thenComparing(ResourceMethodDeclaration::methodName));
                return out;
        }

        private static List<McpEndpointDeclaration> dedupeAndOrderMcpEndpoints(List<McpEndpointDeclaration> in) {
                Map<String, McpEndpointDeclaration> byKey = new LinkedHashMap<>();
                for (McpEndpointDeclaration endpointDeclaration : in)
                        byKey.putIfAbsent(generateMcpEndpointKey(endpointDeclaration), endpointDeclaration);

                List<McpEndpointDeclaration> out = new ArrayList<>(byKey.values());
                out.sort(Comparator.comparing(McpEndpointDeclaration::className));
                return out;
        }

        private record ResourceMethodSpecificityKey(HttpMethod httpMethod,
                                                                                                                                                                                        Boolean sseEventSource,
                                                                                                                                                                                        Boolean hasVarargs,
                                                                                                                                                                                        Long placeholderCount,
                                                                                                                                                                                        Long literalCount) {}

        private record McpEndpointDeclaration(String className) {}
}