ast-mcp-server 0.6.0 → 0.7.1

package/dist/services/project.js

@@ -1,12 +1,184 @@
 import fs from "node:fs";
 import path from "node:path";
 import { Project } from "ts-morph";
-import { findDeclaration } from "./symbols.js";
+import { InMemorySymbolIndex, SYMBOL_INDEX_SCHEMA_VERSION, } from "./symbol-index.js";
+import { addSymbolIndexRuntimeCount, createInitialSymbolIndexRuntimeObservability, readSymbolIndexPersistencePolicy, symbolIndexCachePath, symbolIndexPolicyKey, } from "./symbol-index-policy.js";
+import { openSQLiteSymbolIndexStore, quarantineSQLiteSymbolIndexFile, } from "./symbol-index-sqlite.js";
+import { findDeclaration, sourceFileIndexSymbols } from "./symbols.js";
+import { createProjectWatcher, selectProjectWatchDirectories, } from "./project-watcher.js";
 import { createConfigSnapshot, createWorkspaceSnapshot } from "./workspace.js";
-import { createInitialProjectStatus, createProjectIdentity, projectStatusToProjection, transitionProjectStatus, } from "./project-status.js";
-const MAX_PROJECT_SESSIONS = 8;
+import { createInitialProjectStatus, createProjectIdentity, projectOperationQueueToProjection, projectStatusToProjection, transitionProjectStatus, } from "./project-status.js";
+import { ProjectOperationScheduler, ProjectOperationSchedulerError, } from "./project-operation-scheduler.js";
+import { isCooperativeInterruption, NO_REQUEST_CONTEXT, } from "./request-context.js";
+import { readRuntimePolicy } from "./runtime-policy.js";
+export class ProjectCapacityError extends Error {
+    code = "PROJECT_CAPACITY_EXCEEDED";
+    constructor() {
+        super("Project session capacity exceeded.");
+        this.name = "ProjectCapacityError";
+    }
+}
 const projectSessions = new Map();
 const projectRoots = new WeakMap();
+let projectSessionAccessSequence = 0n;
+let projectRuntimePolicy;
+let projectRuntimeAdmission = "open";
+function nextProjectSessionAccessSequence() {
+    projectSessionAccessSequence += 1n;
+    return projectSessionAccessSequence;
+}
+function getProjectRuntimePolicy() {
+    projectRuntimePolicy ??= readRuntimePolicy();
+    return projectRuntimePolicy;
+}
+function closePersistentSymbolIndex(session) {
+    session.persistentSymbolIndex?.close();
+    session.persistentSymbolIndex = undefined;
+}
+function symbolIndexFailureOperation(reason) {
+    if (reason === "corrupt_storage")
+        return "corruption";
+    if (reason === "migration_failed" || reason === "unsupported_schema")
+        return "migration";
+    if (reason === "read_failed" || reason === "sqlite_read_failed")
+        return "read_failure";
+    if (reason === "write_failed" || reason === "sqlite_write_failed" || reason === "contention") {
+        return "write_failure";
+    }
+    return "fallback";
+}
+function fallbackToMemory(session, reason) {
+    const persistentSymbolIndex = session.persistentSymbolIndex;
+    session.persistentSymbolIndex = undefined;
+    const boundedReason = reason.slice(0, 128);
+    const operation = symbolIndexFailureOperation(boundedReason);
+    const previous = session.context.symbolIndexObservability;
+    session.context = {
+        ...session.context,
+        status: transitionProjectStatus(session.context.status, {
+            type: "index_failed",
+            error: boundedReason,
+        }),
+        symbolIndex: new InMemorySymbolIndex(),
+        symbolIndexBackend: "memory",
+        symbolIndexFallbackReason: boundedReason,
+        symbolIndexReady: false,
+        symbolIndexObservability: {
+            ...session.context.symbolIndexObservability,
+            policy: session.symbolIndexPolicy.mode,
+            policy_reason: session.symbolIndexPolicy.reason,
+            backend: "memory",
+            state: "failed",
+            operation,
+            last_operation: operation,
+            rejected_entries: addSymbolIndexRuntimeCount(previous.rejected_entries),
+            fallback_count: addSymbolIndexRuntimeCount(previous.fallback_count),
+            migration_count: addSymbolIndexRuntimeCount(previous.migration_count, operation === "migration" ? 1 : 0),
+            corruption_count: addSymbolIndexRuntimeCount(previous.corruption_count, operation === "corruption" ? 1 : 0),
+            write_failure_count: addSymbolIndexRuntimeCount(previous.write_failure_count, operation === "write_failure" ? 1 : 0),
+            last_error: boundedReason,
+        },
+    };
+    try {
+        persistentSymbolIndex?.close();
+    }
+    catch {
+        // The compiler-backed memory context was already installed; cleanup is best effort.
+    }
+}
+export async function reportSymbolIndexFailure(projectRoot, reason) {
+    const session = projectSessions.get(resolveTsConfigPath(projectRoot));
+    if (!session)
+        return undefined;
+    const cachePath = symbolIndexCachePath(session.symbolIndexPolicy, session.context.status.project);
+    fallbackToMemory(session, reason);
+    if (cachePath && reason === "corrupt_storage") {
+        try {
+            await quarantineSQLiteSymbolIndexFile(cachePath);
+        }
+        catch {
+            // The compiler-backed memory fallback remains authoritative if quarantine fails.
+        }
+    }
+    return session.context;
+}
+async function ensureSessionSymbolIndex(session, requestContext) {
+    requestContext.checkpoint();
+    const policy = readSymbolIndexPersistencePolicy();
+    if (symbolIndexPolicyKey(policy) !== symbolIndexPolicyKey(session.symbolIndexPolicy)) {
+        closePersistentSymbolIndex(session);
+        session.symbolIndexPolicy = policy;
+        session.context = {
+            ...session.context,
+            status: transitionProjectStatus(session.context.status, { type: "index_disabled" }),
+            symbolIndex: new InMemorySymbolIndex(),
+            symbolIndexBackend: "memory",
+            symbolIndexFallbackReason: null,
+            symbolIndexReady: false,
+            symbolIndexObservability: createInitialSymbolIndexRuntimeObservability(policy),
+        };
+    }
+    if (policy.backend === "memory")
+        return;
+    if (session.persistentSymbolIndex)
+        return;
+    const cachePath = symbolIndexCachePath(policy, session.context.status.project);
+    if (!cachePath)
+        return;
+    try {
+        requestContext.checkpoint();
+        const store = await openSQLiteSymbolIndexStore(cachePath, {
+            busyTimeoutMs: policy.busy_timeout_ms,
+        });
+        try {
+            requestContext.checkpoint();
+        }
+        catch (error) {
+            store.close();
+            throw error;
+        }
+        session.persistentSymbolIndex = store;
+        const migrationPerformed = store.migrationPerformed;
+        session.context = {
+            ...session.context,
+            status: session.context.status.causes.includes("index_failure")
+                ? transitionProjectStatus(session.context.status, { type: "index_recovered" })
+                : transitionProjectStatus(session.context.status, { type: "index_ready" }),
+            symbolIndex: store,
+            symbolIndexBackend: "sqlite",
+            symbolIndexFallbackReason: null,
+            symbolIndexReady: false,
+            symbolIndexObservability: {
+                ...session.context.symbolIndexObservability,
+                policy: policy.mode,
+                policy_reason: policy.reason,
+                backend: "sqlite",
+                state: "rebuilding",
+                operation: "miss",
+                last_operation: migrationPerformed ? "migration" : "miss",
+                migration_count: addSymbolIndexRuntimeCount(session.context.symbolIndexObservability.migration_count, migrationPerformed ? 1 : 0),
+                last_error: null,
+            },
+        };
+    }
+    catch (error) {
+        if (isCooperativeInterruption(error))
+            throw error;
+        const reason = error.code ?? "sqlite_open_failed";
+        if (reason === "corrupt_storage" ||
+            reason === "unsupported_schema" ||
+            reason === "migration_failed" ||
+            reason === "read_failed") {
+            try {
+                await quarantineSQLiteSymbolIndexFile(cachePath);
+            }
+            catch {
+                // Keep the memory fallback even when the corrupt artifact cannot be moved.
+            }
+        }
+        fallbackToMemory(session, String(reason));
+    }
+}
 export function resolveTsConfigPath(projectRoot) {
     const abs = path.resolve(projectRoot);
     const stat = fs.existsSync(abs) ? fs.statSync(abs) : null;
@@ -27,70 +199,219 @@ function buildProjectContext(tsConfigFilePath) {
     const projectRoot = path.dirname(tsConfigFilePath);
     projectRoots.set(project, projectRoot);
     const status = createInitialProjectStatus(createProjectIdentity({ projectRoot, configPath: tsConfigFilePath }), { sourceCount: project.getSourceFiles().length });
-    return { project, projectRoot, tsConfigFilePath, status };
+    return {
+        project,
+        projectRoot,
+        tsConfigFilePath,
+        status,
+        symbolIndex: new InMemorySymbolIndex(),
+        symbolIndexReady: false,
+        symbolIndexBackend: "memory",
+        symbolIndexFallbackReason: null,
+        symbolIndexObservability: createInitialSymbolIndexRuntimeObservability(),
+    };
 }
 export function createFreshProject(projectRoot) {
     return buildProjectContext(resolveTsConfigPath(projectRoot));
 }
-function evictSessions() {
-    if (projectSessions.size < MAX_PROJECT_SESSIONS)
+function closeProjectSession(session) {
+    session.watcher.close();
+    closePersistentSymbolIndex(session);
+}
+function createSessionWatcher(getSession, projectRoot, directories) {
+    return createProjectWatcher({
+        projectRoot,
+        directories,
+        onChange: (files) => {
+            const session = getSession();
+            session.context = {
+                ...session.context,
+                status: transitionProjectStatus(session.context.status, {
+                    type: "source_changed",
+                    files,
+                }),
+            };
+        },
+        onError: (error) => {
+            const session = getSession();
+            session.context = {
+                ...session.context,
+                status: transitionProjectStatus(session.context.status, {
+                    type: "watcher_failed",
+                    error: error instanceof Error ? error.message : String(error),
+                }),
+            };
+        },
+    });
+}
+function sameDirectories(left, right) {
+    return (left.length === right.length && left.every((directory, index) => directory === right[index]));
+}
+function replaceSessionWatcher(session, directories) {
+    if (sameDirectories(session.watchDirectories, directories) &&
+        session.watcher.snapshot().state !== "failed") {
         return;
-    const candidate = [...projectSessions.entries()]
-        .filter(([, session]) => session.activeOperations === 0)
-        .sort((left, right) => left[1].lastAccessedAt - right[1].lastAccessedAt)[0];
-    if (candidate)
+    }
+    const previous = session.watcher;
+    const replacement = createSessionWatcher(() => session, session.context.projectRoot, directories);
+    session.watcher = replacement;
+    session.watchDirectories = directories;
+    replacement.start();
+    previous.close();
+    if (replacement.snapshot().state === "ready") {
+        session.context = {
+            ...session.context,
+            status: transitionProjectStatus(session.context.status, { type: "watcher_recovered" }),
+        };
+    }
+}
+function sessionHasAdmittedOperations(session) {
+    const snapshot = session.scheduler.snapshot();
+    return snapshot.active_operations + snapshot.queued_operations > 0;
+}
+function ensureProjectSessionCapacity(sessionCapacity) {
+    while (projectSessions.size >= sessionCapacity) {
+        const candidate = [...projectSessions.entries()]
+            .filter(([, session]) => !sessionHasAdmittedOperations(session))
+            .sort((left, right) => left[1].lastAccessSequence < right[1].lastAccessSequence
+            ? -1
+            : left[1].lastAccessSequence > right[1].lastAccessSequence
+                ? 1
+                : 0)[0];
+        if (!candidate)
+            throw new ProjectCapacityError();
+        closeProjectSession(candidate[1]);
         projectSessions.delete(candidate[0]);
+    }
+}
+function assertProjectRuntimeAdmissionOpen() {
+    if (projectRuntimeAdmission === "closed") {
+        throw new ProjectOperationSchedulerError("SERVER_SHUTTING_DOWN");
+    }
 }
-function getOrCreateSession(projectRoot) {
+function getOrCreateSession(projectRoot, requestContext = NO_REQUEST_CONTEXT) {
+    assertProjectRuntimeAdmissionOpen();
+    requestContext.checkpoint();
     const tsConfigFilePath = resolveTsConfigPath(projectRoot);
     const existing = projectSessions.get(tsConfigFilePath);
     if (existing)
         return existing;
-    evictSessions();
+    const runtimePolicy = getProjectRuntimePolicy();
+    ensureProjectSessionCapacity(runtimePolicy.maxProjectSessions);
+    const symbolIndexPolicy = readSymbolIndexPersistencePolicy();
+    requestContext.checkpoint();
+    const baseContext = buildProjectContext(tsConfigFilePath);
+    const context = {
+        ...baseContext,
+        symbolIndexObservability: createInitialSymbolIndexRuntimeObservability(symbolIndexPolicy),
+    };
+    const watchDirectories = selectProjectWatchDirectories(context.projectRoot, context.project.getSourceFiles().map((sourceFile) => sourceFile.getFilePath()));
+    const watcher = createSessionWatcher(() => session, context.projectRoot, watchDirectories);
     const session = {
-        context: buildProjectContext(tsConfigFilePath),
-        configDigest: createConfigSnapshot(tsConfigFilePath).digest,
-        queue: Promise.resolve(),
-        activeOperations: 0,
-        runningOperations: 0,
-        queuedOperations: 0,
-        lastAccessedAt: Date.now(),
+        context,
+        watcher,
+        watchDirectories,
+        configDigest: (() => {
+            requestContext.checkpoint();
+            return createConfigSnapshot(tsConfigFilePath).digest;
+        })(),
+        fingerprints: new Map(),
+        compilerStateUntrusted: false,
+        scheduler: new ProjectOperationScheduler({
+            queueCapacity: runtimePolicy.maxQueuedOperationsPerProject,
+            queueWaitTimeoutMs: runtimePolicy.queueWaitTimeoutMs,
+            operationDeadlineMs: runtimePolicy.operationDeadlineMs,
+        }),
+        lastAccessSequence: nextProjectSessionAccessSequence(),
+        symbolIndexPolicy,
     };
     projectSessions.set(tsConfigFilePath, session);
+    session.watcher.start();
+    if (session.watcher.snapshot().state === "ready") {
+        session.context = {
+            ...session.context,
+            status: transitionProjectStatus(session.context.status, { type: "watcher_recovered" }),
+        };
+    }
     return session;
 }
 function getQueueStatus(session) {
-    return {
-        state: session.runningOperations > 0 ? "running" : session.queuedOperations > 0 ? "queued" : "idle",
-        active_operations: session.runningOperations,
-        queued_operations: session.queuedOperations,
-    };
+    const snapshot = session.scheduler.snapshot();
+    return projectOperationQueueToProjection(snapshot, snapshot.queue_capacity);
+}
+export function getProjectOperationQueueSnapshot(projectRoot) {
+    const session = projectSessions.get(resolveTsConfigPath(projectRoot));
+    if (!session)
+        throw new Error("Project session not found.");
+    return getQueueStatus(session);
 }
-async function synchronizeSession(session) {
+export function getProjectSessionRegistrySnapshot() {
+    const activeSessions = [...projectSessions.values()].filter((session) => sessionHasAdmittedOperations(session)).length;
+    return Object.freeze({
+        session_count: projectSessions.size,
+        active_sessions: activeSessions,
+        idle_sessions: projectSessions.size - activeSessions,
+        session_capacity: getProjectRuntimePolicy().maxProjectSessions,
+    });
+}
+async function synchronizeSession(session, requestContext) {
     let syncFailureCause = "compiler_rebuild";
     let currentConfigDigest;
+    let compilerStateMayHaveAdvanced = false;
     try {
+        requestContext.checkpoint();
         currentConfigDigest = createConfigSnapshot(session.context.tsConfigFilePath).digest;
-        if (currentConfigDigest !== session.configDigest) {
-            let status = transitionProjectStatus(session.context.status, { type: "config_changed" });
+        const compilerConfigChanged = currentConfigDigest !== session.configDigest;
+        if (compilerConfigChanged || session.compilerStateUntrusted) {
+            let status = session.context.status;
+            if (compilerConfigChanged) {
+                status = transitionProjectStatus(status, { type: "config_changed" });
+            }
             status = transitionProjectStatus(status, { type: "compiler_rebuild_started" });
+            const symbolIndexObservability = session.context.symbolIndexObservability;
+            closePersistentSymbolIndex(session);
             const rebuilt = buildProjectContext(session.context.tsConfigFilePath);
-            session.context = { ...rebuilt, status };
+            session.context = { ...rebuilt, status, symbolIndexObservability };
+            session.compilerStateUntrusted = false;
         }
         const { project, tsConfigFilePath } = session.context;
         syncFailureCause = "source_change";
-        const refreshSourceFiles = async () => {
-            project.addSourceFilesFromTsConfig(tsConfigFilePath);
-            await Promise.all(project.getSourceFiles().map((sourceFile) => sourceFile.refreshFromFileSystem()));
-        };
-        await refreshSourceFiles();
-        const snapshot = createWorkspaceSnapshot(session.context);
+        requestContext.checkpoint();
+        compilerStateMayHaveAdvanced = true;
+        project.addSourceFilesFromTsConfig(tsConfigFilePath);
+        for (const sourceFile of project.getSourceFiles()) {
+            requestContext.checkpoint();
+            if (!fs.existsSync(sourceFile.getFilePath()))
+                project.removeSourceFile(sourceFile);
+        }
+        requestContext.checkpoint();
+        replaceSessionWatcher(session, selectProjectWatchDirectories(session.context.projectRoot, project.getSourceFiles().map((sourceFile) => sourceFile.getFilePath())));
+        requestContext.checkpoint();
+        const snapshot = createWorkspaceSnapshot(session.context, {
+            previousFingerprints: session.fingerprints,
+            verifyContentHash: true,
+        });
         if (snapshot.configDigest !== currentConfigDigest) {
             syncFailureCause = "config_change";
             throw new Error("Project configuration changed during synchronization. Retry the operation.");
         }
-        await refreshSourceFiles();
-        const verificationSnapshot = createWorkspaceSnapshot(session.context);
+        const changedPaths = new Set([
+            ...snapshot.fingerprintChanges.added,
+            ...snapshot.fingerprintChanges.changed,
+        ]);
+        requestContext.checkpoint();
+        await Promise.all(project.getSourceFiles().map(async (sourceFile) => {
+            requestContext.checkpoint();
+            const absoluteFilePath = fs.realpathSync(sourceFile.getFilePath());
+            if (changedPaths.has(absoluteFilePath))
+                await sourceFile.refreshFromFileSystem();
+        }));
+        requestContext.checkpoint();
+        const verificationSnapshot = createWorkspaceSnapshot(session.context, {
+            previousFingerprints: snapshot.fingerprints,
+            verifyContentHash: true,
+        });
+        requestContext.checkpoint();
         if (verificationSnapshot.configDigest !== currentConfigDigest) {
             syncFailureCause = "config_change";
             throw new Error("Project configuration changed during synchronization. Retry the operation.");
@@ -99,6 +420,165 @@ async function synchronizeSession(session) {
             syncFailureCause = "source_change";
             throw new Error("Project source changed during synchronization. Retry the operation.");
         }
+        requestContext.checkpoint();
+        await ensureSessionSymbolIndex(session, requestContext);
+        const sourceFiles = session.context.project.getSourceFiles();
+        const currentIndexFiles = sourceFiles.map((sourceFile) => {
+            requestContext.checkpoint();
+            const absoluteFilePath = fs.realpathSync(sourceFile.getFilePath());
+            const fingerprint = verificationSnapshot.fingerprints.get(absoluteFilePath);
+            if (!fingerprint) {
+                throw new Error(`No verified fingerprint found for ${absoluteFilePath}.`);
+            }
+            return {
+                file_path: path
+                    .relative(session.context.projectRoot, sourceFile.getFilePath())
+                    .replaceAll(path.sep, "/"),
+                content_hash: fingerprint.content_hash,
+            };
+        });
+        let existingIndexEntries;
+        try {
+            requestContext.checkpoint();
+            existingIndexEntries = await session.context.symbolIndex.load(session.context.status.project, SYMBOL_INDEX_SCHEMA_VERSION);
+            requestContext.checkpoint();
+        }
+        catch (error) {
+            if (isCooperativeInterruption(error))
+                throw error;
+            if (session.context.symbolIndexBackend !== "sqlite")
+                throw error;
+            fallbackToMemory(session, error.code ?? "sqlite_read_failed");
+            requestContext.checkpoint();
+            existingIndexEntries = await session.context.symbolIndex.load(session.context.status.project, SYMBOL_INDEX_SCHEMA_VERSION);
+            requestContext.checkpoint();
+        }
+        if (session.context.symbolIndexBackend === "sqlite") {
+            const cacheWarm = existingIndexEntries.length > 0;
+            session.context = {
+                ...session.context,
+                symbolIndexObservability: {
+                    ...session.context.symbolIndexObservability,
+                    state: "rebuilding",
+                    operation: cacheWarm ? "hit" : "miss",
+                    last_operation: cacheWarm ? "hit" : "miss",
+                    loaded_entries: addSymbolIndexRuntimeCount(session.context.symbolIndexObservability.loaded_entries, existingIndexEntries.length),
+                    accepted_entries: addSymbolIndexRuntimeCount(session.context.symbolIndexObservability.accepted_entries, existingIndexEntries.length),
+                    cache_hits: addSymbolIndexRuntimeCount(session.context.symbolIndexObservability.cache_hits, cacheWarm ? 1 : 0),
+                    cache_misses: addSymbolIndexRuntimeCount(session.context.symbolIndexObservability.cache_misses, cacheWarm ? 0 : 1),
+                },
+            };
+        }
+        const existingByPath = new Map(existingIndexEntries.map((entry) => [entry.file_path, entry]));
+        const fingerprintChangedFiles = new Set([
+            ...verificationSnapshot.fingerprintChanges.added,
+            ...verificationSnapshot.fingerprintChanges.changed,
+        ].map((filePath) => path.relative(session.context.projectRoot, filePath).replaceAll(path.sep, "/")));
+        const configChanged = existingIndexEntries.some((entry) => entry.config_digest !== verificationSnapshot.configDigest);
+        const filesToRebuild = new Set(currentIndexFiles
+            .filter((file) => {
+            const previous = existingByPath.get(file.file_path);
+            return (configChanged ||
+                fingerprintChangedFiles.has(file.file_path) ||
+                !previous ||
+                previous.content_hash !== file.content_hash ||
+                previous.config_digest !== verificationSnapshot.configDigest);
+        })
+            .map((file) => file.file_path));
+        const indexFiles = sourceFiles
+            .filter((sourceFile) => {
+            requestContext.checkpoint();
+            const filePath = path
+                .relative(session.context.projectRoot, sourceFile.getFilePath())
+                .replaceAll(path.sep, "/");
+            return filesToRebuild.has(filePath);
+        })
+            .map((sourceFile) => {
+            requestContext.checkpoint();
+            const absoluteFilePath = fs.realpathSync(sourceFile.getFilePath());
+            const fingerprint = verificationSnapshot.fingerprints.get(absoluteFilePath);
+            if (!fingerprint) {
+                throw new Error(`No verified fingerprint found for ${absoluteFilePath}.`);
+            }
+            return {
+                file_path: path
+                    .relative(session.context.projectRoot, sourceFile.getFilePath())
+                    .replaceAll(path.sep, "/"),
+                content_hash: fingerprint.content_hash,
+                symbols: sourceFileIndexSymbols(sourceFile, session.context.projectRoot),
+            };
+        });
+        try {
+            requestContext.checkpoint();
+            const refreshResult = await session.context.symbolIndex.refresh({
+                project: session.context.status.project,
+                config_digest: verificationSnapshot.configDigest,
+                current_files: currentIndexFiles,
+                files: indexFiles,
+                last_indexed_at: new Date().toISOString(),
+            });
+            requestContext.checkpoint();
+            await session.context.symbolIndex.flush();
+            requestContext.checkpoint();
+            session.context = {
+                ...session.context,
+                symbolIndexReady: true,
+                symbolIndexObservability: session.context.symbolIndexBackend === "sqlite"
+                    ? {
+                        ...session.context.symbolIndexObservability,
+                        state: "ready",
+                        operation: refreshResult.rebuilt_files.length > 0 ? "rebuild" : "hit",
+                        last_operation: refreshResult.rebuilt_files.length > 0 ? "rebuild" : "hit",
+                        last_successful_persistence_at: new Date().toISOString(),
+                        rebuilt_files: addSymbolIndexRuntimeCount(session.context.symbolIndexObservability.rebuilt_files, refreshResult.rebuilt_files.length),
+                        reused_files: addSymbolIndexRuntimeCount(session.context.symbolIndexObservability.reused_files, refreshResult.reused_files.length),
+                        removed_files: addSymbolIndexRuntimeCount(session.context.symbolIndexObservability.removed_files, refreshResult.removed_files.length),
+                    }
+                    : session.context.symbolIndexObservability,
+            };
+        }
+        catch (error) {
+            if (isCooperativeInterruption(error))
+                throw error;
+            if (session.context.symbolIndexBackend === "sqlite") {
+                fallbackToMemory(session, error.code ?? "sqlite_write_failed");
+                try {
+                    const fallbackFiles = sourceFiles.map((sourceFile) => {
+                        requestContext.checkpoint();
+                        const absoluteFilePath = fs.realpathSync(sourceFile.getFilePath());
+                        const fingerprint = verificationSnapshot.fingerprints.get(absoluteFilePath);
+                        if (!fingerprint) {
+                            throw new Error(`No verified fingerprint found for ${absoluteFilePath}.`);
+                        }
+                        return {
+                            file_path: path
+                                .relative(session.context.projectRoot, sourceFile.getFilePath())
+                                .replaceAll(path.sep, "/"),
+                            content_hash: fingerprint.content_hash,
+                            symbols: sourceFileIndexSymbols(sourceFile, session.context.projectRoot),
+                        };
+                    });
+                    requestContext.checkpoint();
+                    await session.context.symbolIndex.refresh({
+                        project: session.context.status.project,
+                        config_digest: verificationSnapshot.configDigest,
+                        current_files: currentIndexFiles,
+                        files: fallbackFiles,
+                        last_indexed_at: new Date().toISOString(),
+                    });
+                    requestContext.checkpoint();
+                    session.context = { ...session.context, symbolIndexReady: true };
+                }
+                catch (fallbackError) {
+                    if (isCooperativeInterruption(fallbackError))
+                        throw fallbackError;
+                    session.context = { ...session.context, symbolIndexReady: false };
+                }
+            }
+            else {
+                session.context = { ...session.context, symbolIndexReady: false };
+            }
+        }
         const status = transitionProjectStatus(session.context.status, {
             type: "sync_succeeded",
             sourceCount: verificationSnapshot.sourceFileCount,
@@ -110,8 +590,14 @@ async function synchronizeSession(session) {
         });
         session.context = { ...session.context, status };
         session.configDigest = verificationSnapshot.configDigest;
+        session.fingerprints = verificationSnapshot.fingerprints;
+        session.compilerStateUntrusted = false;
     }
     catch (error) {
+        if (compilerStateMayHaveAdvanced)
+            session.compilerStateUntrusted = true;
+        if (isCooperativeInterruption(error))
+            throw error;
         const status = transitionProjectStatus(session.context.status, {
             type: "sync_failed",
             cause: syncFailureCause,
@@ -121,43 +607,66 @@ async function synchronizeSession(session) {
         throw error;
     }
 }
-async function runSessionWithSyncPolicy(session, operation, allowSynchronizationFailure) {
-    session.activeOperations += 1;
-    session.queuedOperations += 1;
-    let release;
-    const previous = session.queue;
-    session.queue = new Promise((resolve) => {
-        release = resolve;
-    });
-    await previous;
-    session.queuedOperations -= 1;
-    session.runningOperations += 1;
-    try {
+async function runSessionWithSyncPolicy(session, operation, allowSynchronizationFailure, requestContext) {
+    requestContext.checkpoint();
+    return session.scheduler.run(async (operationContext) => {
+        operationContext.checkpoint();
         try {
-            await synchronizeSession(session);
+            await synchronizeSession(session, operationContext);
         }
         catch (error) {
-            if (!allowSynchronizationFailure)
+            if (!allowSynchronizationFailure || isCooperativeInterruption(error))
                 throw error;
         }
-        session.lastAccessedAt = Date.now();
-        return await operation(session.context);
-    }
-    finally {
-        session.runningOperations -= 1;
-        session.activeOperations -= 1;
-        release?.();
-    }
+        operationContext.checkpoint();
+        operationContext.markExecuting();
+        session.lastAccessSequence = nextProjectSessionAccessSequence();
+        return operation(session.context, operationContext);
+    }, { signal: requestContext.signal });
+}
+export async function withProject(projectRoot, operation, requestContext = NO_REQUEST_CONTEXT) {
+    requestContext.checkpoint();
+    return runSessionWithSyncPolicy(getOrCreateSession(projectRoot, requestContext), operation, false, requestContext);
 }
-export async function withProject(projectRoot, operation) {
-    return runSessionWithSyncPolicy(getOrCreateSession(projectRoot), operation, false);
+export async function withProjectOperation(projectRoot, operation, requestContext = NO_REQUEST_CONTEXT) {
+    requestContext.checkpoint();
+    const session = getOrCreateSession(projectRoot, requestContext);
+    return session.scheduler.run((operationContext) => {
+        operationContext.checkpoint();
+        operationContext.markExecuting();
+        session.lastAccessSequence = nextProjectSessionAccessSequence();
+        return operation(operationContext);
+    }, { signal: requestContext.signal });
 }
-export async function getProjectStatus(projectRoot) {
-    const session = getOrCreateSession(projectRoot);
-    return runSessionWithSyncPolicy(session, (context) => ({
-        ...projectStatusToProjection(context.status),
-        operation_queue: getQueueStatus(session),
-    }), true);
+export async function getProjectStatus(projectRoot, requestContext = NO_REQUEST_CONTEXT) {
+    requestContext.checkpoint();
+    const session = getOrCreateSession(projectRoot, requestContext);
+    return runSessionWithSyncPolicy(session, async (context, operationContext) => {
+        let effectiveContext = context;
+        let indexedCount = 0;
+        if (context.symbolIndexBackend === "sqlite" && context.symbolIndexReady) {
+            try {
+                operationContext.checkpoint();
+                indexedCount = (await context.symbolIndex.load(context.status.project, SYMBOL_INDEX_SCHEMA_VERSION)).length;
+                operationContext.checkpoint();
+            }
+            catch (error) {
+                if (isCooperativeInterruption(error))
+                    throw error;
+                fallbackToMemory(session, error.code ?? "sqlite_read_failed");
+                effectiveContext = session.context;
+                indexedCount = 0;
+            }
+        }
+        return {
+            ...projectStatusToProjection(effectiveContext.status),
+            index: { state: effectiveContext.symbolIndexObservability.state },
+            indexed_count: indexedCount,
+            last_successful_index_at: effectiveContext.symbolIndexObservability.last_successful_persistence_at,
+            index_observability: { ...effectiveContext.symbolIndexObservability },
+            operation_queue: getQueueStatus(session),
+        };
+    }, true, requestContext);
 }
 // Compatibility API for internal scripts. MCP tools should use withProject().
 export function getProject(projectRoot) {
@@ -165,10 +674,81 @@ export function getProject(projectRoot) {
 }
 export function invalidateProject(projectRoot) {
     const tsConfigFilePath = resolveTsConfigPath(projectRoot);
+    const session = projectSessions.get(tsConfigFilePath);
+    if (session)
+        closeProjectSession(session);
+    projectSessions.delete(tsConfigFilePath);
+}
+export function invalidateProjectIfIdle(projectRoot, options = {}) {
+    const tsConfigFilePath = resolveTsConfigPath(projectRoot);
+    const session = projectSessions.get(tsConfigFilePath);
+    if (!session)
+        return true;
+    const queue = session.scheduler.snapshot();
+    if (queue.active_operations > 0 ||
+        queue.queued_operations > 0 ||
+        (options.preserveCancellationTelemetry === true && queue.cancelled_operations > 0)) {
+        return false;
+    }
+    closeProjectSession(session);
     projectSessions.delete(tsConfigFilePath);
+    return true;
 }
 export function clearProjectSessions() {
+    for (const session of projectSessions.values()) {
+        closeProjectSession(session);
+    }
+    projectSessions.clear();
+    projectSessionAccessSequence = 0n;
+    projectRuntimePolicy = undefined;
+    projectRuntimeAdmission = "open";
+}
+export function prepareProjectRuntimeForStartup() {
+    if (projectSessions.size !== 0) {
+        throw new Error("Cannot start a project runtime while sessions remain open.");
+    }
+    projectRuntimeAdmission = "open";
+}
+export function getProjectRuntimeShutdownSnapshot() {
+    let activeOperations = 0;
+    let queuedOperations = 0;
+    let completionCriticalOperations = 0;
+    for (const session of projectSessions.values()) {
+        const snapshot = session.scheduler.shutdownSnapshot();
+        activeOperations += snapshot.active_operations;
+        queuedOperations += snapshot.queued_operations;
+        completionCriticalOperations += snapshot.completion_critical_operations;
+    }
+    return Object.freeze({
+        admission: projectRuntimeAdmission,
+        session_count: projectSessions.size,
+        active_operations: activeOperations,
+        queued_operations: queuedOperations,
+        completion_critical_operations: completionCriticalOperations,
+    });
+}
+export function beginProjectShutdown() {
+    projectRuntimeAdmission = "closed";
+    for (const session of projectSessions.values())
+        session.scheduler.beginShutdown();
+    return getProjectRuntimeShutdownSnapshot();
+}
+export async function waitForProjectOperationsToDrain() {
+    await Promise.all([...projectSessions.values()].map((session) => session.scheduler.waitForIdle()));
+}
+export async function waitForProjectCompletionCriticalOperationsToDrain() {
+    await Promise.all([...projectSessions.values()].map((session) => session.scheduler.waitForCompletionCriticalOperationsToDrain()));
+}
+export function closeDrainedProjectSessions() {
+    const snapshot = getProjectRuntimeShutdownSnapshot();
+    if (snapshot.active_operations !== 0 || snapshot.queued_operations !== 0) {
+        throw new Error("Cannot close project sessions while operations are active.");
+    }
+    for (const session of projectSessions.values())
+        closeProjectSession(session);
     projectSessions.clear();
+    projectSessionAccessSequence = 0n;
+    projectRuntimePolicy = undefined;
 }
 export function getSourceFileOrThrow(project, filePath) {
     const projectRoot = projectRoots.get(project) ?? process.cwd();