typescript 7.1.0-dev.20261018.1 → 7.1.0-dev.20261020.3

package/dist/api/async/api.js

@@ -21,7 +21,7 @@ import { TypePredicateKind } from "#enums/typePredicateKind";
 import { ModifierFlags, unescapeLeadingUnderscores, } from "../../ast/index.js";
 import { assertNever } from "../../internal/utils.js";
 import { encodeNode, uint8ArrayToBase64, } from "../node/encoder.js";
-import { decodeNode, getNodeId, parseNodeHandleFromCompiler, readParseOptionsKey, readSourceFileHash, readSourceFileLease, RemoteNode, RemoteSourceFile, } from "../node/node.js";
+import { decodeNode, getNodeId, getNodeRequestHandle, parseNodeHandleFromCompiler, readParseOptionsKey, readSourceFileHash, readSourceFileLease, RemoteNode, RemoteSourceFile, } from "../node/node.js";
 import { Wtf8Decoder } from "../node/wtf8.js";
 import { canonicalize, CaseSensitivity, pathKey, toRootedDirectoryPath, toRootedPath, } from "../path.js";
 import { prepareCompilerOptions } from "../prepareCompilerOptions.generated.js";
@@ -735,13 +735,15 @@ export class ModuleResolver {
 }
 class SnapshotObjectRegistry {
     symbols = new Map();
+    nodeHandles = new Map();
     projectRegistries = new Map();
     snapshotId;
+    disposed = false;
     constructor(snapshotId) {
         this.snapshotId = snapshotId;
     }
     addProjectRegistry(registry) {
-        this.projectRegistries.set(registry.project.id, registry);
+        this.projectRegistries.set(registry.project.handle, registry);
     }
     getOrCreateSymbol(data) {
         const reference = data.reference;
@@ -763,8 +765,19 @@ class SnapshotObjectRegistry {
     getSymbol(id) {
         return this.symbols.get(id);
     }
+    getOrCreateNodeHandle(handle, project) {
+        let node = this.nodeHandles.get(handle);
+        if (!node) {
+            node = new NodeHandle(handle, project);
+            if (!this.disposed)
+                this.nodeHandles.set(handle, node);
+        }
+        return node;
+    }
     clear() {
+        this.disposed = true;
         this.symbols.clear();
+        this.nodeHandles.clear();
     }
 }
 class ProjectObjectRegistry {
@@ -824,7 +837,7 @@ class ProjectObjectRegistry {
         return this.types.get(id);
     }
     createNodeHandle(handle) {
-        return new NodeHandle(handle, this.project);
+        return this.snapshotRegistry.getOrCreateNodeHandle(handle, this.project);
     }
     getOrCreateSignature(data) {
         let sig = this.signatures.get(data.id);
@@ -856,7 +869,7 @@ class ProjectObjectRegistry {
         }
         const data = await this.client.apiRequest(method, {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             objectId: source.id,
         });
         if (!data)
@@ -879,7 +892,7 @@ class ProjectObjectRegistry {
             ? await this.client.apiRequest(method, { symbol: source.reference })
             : await this.client.apiRequest(method, {
                 snapshot: this.snapshotId,
-                project: this.project.id,
+                project: this.project.handle,
                 objectId: source.id,
             });
         if (!data)
@@ -894,7 +907,7 @@ class ProjectObjectRegistry {
             return cached;
         const data = await this.client.apiRequest(method, {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             objectId: source.id,
         });
         if (!data)
@@ -918,7 +931,7 @@ class ProjectObjectRegistry {
         }
         const typesData = await this.client.apiRequest(method, {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             objectId: source.id,
         });
         if (typesData == null)
@@ -945,7 +958,7 @@ class ProjectObjectRegistry {
             ? await this.client.apiRequest(method, { symbol: source.reference })
             : await this.client.apiRequest(method, {
                 snapshot: this.snapshotId,
-                project: this.project.id,
+                project: this.project.handle,
                 objectId: source.id,
             });
         return data?.map(symbol => this.getOrCreateSymbol(symbol)) ?? [];
@@ -955,7 +968,7 @@ class ProjectObjectRegistry {
     async fetchBaseTypes(source) {
         const typesData = await this.client.apiRequest("getBaseTypes", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             type: source.id,
         });
         if (typesData == null)
@@ -965,7 +978,7 @@ class ProjectObjectRegistry {
     async fetchPropertiesOfType(source) {
         const data = await this.client.apiRequest("getPropertiesOfType", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             type: source.id,
         });
         return data ? data.map(symbol => this.getOrCreateSymbol(symbol)) : [];
@@ -973,7 +986,7 @@ class ProjectObjectRegistry {
     async fetchApparentPropertiesOfType(source) {
         const data = await this.client.apiRequest("getApparentPropertiesOfType", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             objectId: source.id,
         });
         return data ? data.map(symbol => this.getOrCreateSymbol(symbol)) : [];
@@ -981,7 +994,7 @@ class ProjectObjectRegistry {
     async fetchPropertyOfType(source, name) {
         const data = await this.client.apiRequest("getPropertyOfType", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             type: source.id,
             name,
         });
@@ -990,7 +1003,7 @@ class ProjectObjectRegistry {
     async fetchSignaturesOfType(source, kind) {
         const data = await this.client.apiRequest("getSignaturesOfType", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             type: source.id,
             kind,
         });
@@ -999,7 +1012,7 @@ class ProjectObjectRegistry {
     async fetchIndexInfosOfType(source) {
         const data = await this.client.apiRequest("getIndexInfosOfType", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             type: source.id,
         });
         if (!data)
@@ -1008,13 +1021,13 @@ class ProjectObjectRegistry {
             keyType: this.getOrCreateType(info.keyType),
             valueType: this.getOrCreateType(info.valueType),
             isReadonly: info.isReadonly ?? false,
-            declaration: info.declaration ? new NodeHandle(info.declaration, this.project) : undefined,
+            declaration: info.declaration ? this.createNodeHandle(info.declaration) : undefined,
         }));
     }
     async fetchTypeParameterAtPosition(source, pos) {
         const data = await this.client.apiRequest("getTypeParameterAtPosition", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             signature: source.id,
             index: pos,
         });
@@ -1025,6 +1038,11 @@ export class Project {
     /** @internal */
     api;
     id;
+    /**
+     * Server identity for this project's lifetime across snapshots.
+     * @internal
+     */
+    handle;
     configFileName;
     currentDirectory;
     dirty;
@@ -1034,6 +1052,7 @@ export class Project {
     languageService;
     constructor(data, snapshotId, toPath, api, snapshotRegistry) {
         this.id = data.id;
+        this.handle = data.handle;
         this.api = api;
         this.configFileName = data.configFileName;
         this.currentDirectory = data.currentDirectory;
@@ -1081,7 +1100,7 @@ export class LanguageService {
         });
         const data = await this.client.apiRequest("getImportAdderEdits", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             file,
             actions: requestActions,
         });
@@ -1105,31 +1124,31 @@ export class LanguageService {
     async getReferencedSymbolsForNode(node, position) {
         const data = await this.client.apiRequest("getReferencedSymbolsForNode", {
             snapshot: this.snapshotId,
-            project: this.project.id,
-            node: getNodeId(node),
+            project: this.project.handle,
+            node: getNodeRequestHandle(node),
             position,
         });
         return (data ?? []).map(entry => ({
-            definition: new NodeHandle(entry.definition, this.project),
+            definition: this.objectRegistry.createNodeHandle(entry.definition),
             symbol: entry.symbol ? this.objectRegistry.getOrCreateSymbol(entry.symbol) : undefined,
-            references: (entry.references ?? []).map(h => new NodeHandle(h, this.project)),
+            references: (entry.references ?? []).map(h => this.objectRegistry.createNodeHandle(h)),
         }));
     }
     async getSignatureUsage(signatureDecl) {
         const data = await this.client.apiRequest("getSignatureUsages", {
             snapshot: this.snapshotId,
-            project: this.project.id,
-            signatureDecl: getNodeId(signatureDecl),
+            project: this.project.handle,
+            signatureDecl: getNodeRequestHandle(signatureDecl),
         });
         return (data ?? []).map(entry => ({
-            name: new NodeHandle(entry.name, this.project),
-            call: entry.call ? new NodeHandle(entry.call, this.project) : undefined,
+            name: this.objectRegistry.createNodeHandle(entry.name),
+            call: entry.call ? this.objectRegistry.createNodeHandle(entry.call) : undefined,
         }));
     }
     async getCompletionsAtPosition(document, position, options) {
         const data = await this.client.apiRequest("getCompletionsAtPosition", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             file: document,
             position,
             triggerCharacter: options?.triggerCharacter,
@@ -1159,7 +1178,7 @@ export class LanguageService {
         const base64 = uint8ArrayToBase64(encoded);
         return this.client.apiRequest("formatNodeForInsertion", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             file,
             position,
             data: base64,
@@ -1238,7 +1257,7 @@ export class Program {
         // Fetch from server
         const binaryData = await this.client.apiRequestBinary("getSourceFile", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             file,
         });
         if (!binaryData) {
@@ -1251,7 +1270,7 @@ export class Program {
     async getResolvedModule(file, moduleName, mode) {
         const result = await this.client.apiRequest("getResolvedModule", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             file,
             moduleName,
             mode,
@@ -1261,15 +1280,15 @@ export class Program {
     async getModeForUsageLocation(file, usage) {
         return this.client.apiRequest("getModeForUsageLocation", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             file,
-            usage: getNodeId(usage),
+            usage: getNodeRequestHandle(usage),
         });
     }
     async getModeForResolutionAtIndex(file, index) {
         return this.client.apiRequest("getModeForResolutionAtIndex", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             file,
             index,
         });
@@ -1277,8 +1296,8 @@ export class Program {
     async getResolvedModuleFromModuleSpecifier(moduleSpecifier, sourceFile) {
         const result = await this.client.apiRequest("getResolvedModuleFromModuleSpecifier", {
             snapshot: this.snapshotId,
-            project: this.project.id,
-            moduleSpecifier: getNodeId(moduleSpecifier),
+            project: this.project.handle,
+            moduleSpecifier: getNodeRequestHandle(moduleSpecifier),
             sourceFile,
         });
         return result ?? undefined;
@@ -1286,7 +1305,7 @@ export class Program {
     async getResolvedTypeReferenceDirective(file, typeDirectiveName, mode) {
         const result = await this.client.apiRequest("getResolvedTypeReferenceDirective", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             file,
             typeDirectiveName,
             mode,
@@ -1296,7 +1315,7 @@ export class Program {
     async getResolvedTypeReferenceDirectiveFromTypeReferenceDirective(typeReferenceDirective, sourceFile) {
         const result = await this.client.apiRequest("getResolvedTypeReferenceDirectiveFromTypeReferenceDirective", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             sourceFile,
             typeDirectiveName: typeReferenceDirective.fileName,
             resolutionMode: typeReferenceDirective.resolutionMode,
@@ -1306,7 +1325,7 @@ export class Program {
     async getSourceFileNames() {
         const data = await this.client.apiRequest("getSourceFileNames", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
         });
         return data ?? [];
     }
@@ -1337,7 +1356,7 @@ export class Program {
         // client-provided path text as untrusted input.
         const data = await this.client.apiRequest("getSourceFileMetadata", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             file: path,
         });
         return data ?? undefined;
@@ -1370,7 +1389,7 @@ export class Program {
     async getConfigFileNames() {
         const data = await this.client.apiRequest("getConfigFileNames", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
         });
         return data ?? [];
     }
@@ -1381,7 +1400,7 @@ export class Program {
     async getConfigSourceFile(file) {
         const binaryData = await this.client.apiRequestBinary("getConfigSourceFile", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             file,
         });
         if (!binaryData) {
@@ -1399,7 +1418,7 @@ export class Program {
                 : [file];
         const data = await this.client.apiRequest("getSyntacticDiagnostics", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             files,
         });
         return data ?? [];
@@ -1414,7 +1433,7 @@ export class Program {
                 : [file];
         const data = await this.client.apiRequest("getBindDiagnostics", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             files,
         });
         return data ?? [];
@@ -1429,7 +1448,7 @@ export class Program {
                 : [file];
         const data = await this.client.apiRequest("getSemanticDiagnostics", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             files,
         });
         return data ?? [];
@@ -1444,7 +1463,7 @@ export class Program {
                 : [file];
         const data = await this.client.apiRequest("getSuggestionDiagnostics", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             files,
         });
         return data ?? [];
@@ -1459,7 +1478,7 @@ export class Program {
                 : [file];
         const data = await this.client.apiRequest("getDeclarationDiagnostics", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             files,
         });
         return data ?? [];
@@ -1470,7 +1489,7 @@ export class Program {
     async getProgramDiagnostics() {
         const data = await this.client.apiRequest("getProgramDiagnostics", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
         });
         return data ?? [];
     }
@@ -1480,7 +1499,7 @@ export class Program {
     async getGlobalDiagnostics() {
         const data = await this.client.apiRequest("getGlobalDiagnostics", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
         });
         return data ?? [];
     }
@@ -1490,7 +1509,7 @@ export class Program {
     async getConfigFileParsingDiagnostics() {
         const data = await this.client.apiRequest("getConfigFileParsingDiagnostics", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
         });
         return data ?? [];
     }
@@ -1502,7 +1521,7 @@ export class Program {
     async emit(emitOnly) {
         const response = await this.client.apiRequest("emit", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             emitOnly,
         });
         const fileSystem = response.emittedFilesContents.length
@@ -1524,7 +1543,7 @@ export class Program {
     async emitToString(emitOnly) {
         const response = await this.client.apiRequest("emitToString", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             emitOnly,
         });
         return toEmitOutput(response);
@@ -1535,7 +1554,7 @@ export class Program {
     async getJavaScriptEmit(files) {
         const response = await this.client.apiRequest("getJavaScriptEmit", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             files,
         });
         return toEmitOutput(response);
@@ -1546,7 +1565,7 @@ export class Program {
     async getDeclarationEmit(files) {
         const response = await this.client.apiRequest("getDeclarationEmit", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             files,
         });
         return toEmitOutput(response);
@@ -1658,7 +1677,7 @@ export class Checker {
     async getMergedSymbol(symbol) {
         const data = await this.client.apiRequest("getMergedSymbol", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             symbol: symbol.reference,
         });
         return this.objectRegistry.getOrCreateSymbol(data);
@@ -1670,8 +1689,8 @@ export class Checker {
     async getSymbolOfNode(node) {
         const data = await this.client.apiRequest("getSymbolOfNode", {
             snapshot: this.snapshotId,
-            project: this.project.id,
-            location: getNodeId(node),
+            project: this.project.handle,
+            location: getNodeRequestHandle(node),
         });
         return data ? this.objectRegistry.getOrCreateSymbol(data) : undefined;
     }
@@ -1679,8 +1698,8 @@ export class Checker {
     async getSymbolOfDeclaration(node) {
         const data = await this.client.apiRequest("getSymbolOfDeclarationForChecker", {
             snapshot: this.snapshotId,
-            project: this.project.id,
-            location: getNodeId(node),
+            project: this.project.handle,
+            location: getNodeRequestHandle(node),
         });
         // Declarations normally have symbols, but preserve unexpected null results at runtime.
         return (data && this.objectRegistry.getOrCreateSymbol(data));
@@ -1689,7 +1708,7 @@ export class Checker {
     async getParentOfSymbol(symbol) {
         const data = await this.client.apiRequest("getParentOfSymbolForChecker", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             symbol: symbol.reference,
         });
         return data ? this.objectRegistry.getOrCreateSymbol(data) : undefined;
@@ -1698,15 +1717,15 @@ export class Checker {
         if (Array.isArray(nodeOrNodes)) {
             const data = await this.client.apiRequest("getSymbolsAtLocations", {
                 snapshot: this.snapshotId,
-                project: this.project.id,
-                locations: nodeOrNodes.map(node => getNodeId(node)),
+                project: this.project.handle,
+                locations: nodeOrNodes.map(node => getNodeRequestHandle(node)),
             });
             return data.map(d => d ? this.objectRegistry.getOrCreateSymbol(d) : undefined);
         }
         const data = await this.client.apiRequest("getSymbolAtLocation", {
             snapshot: this.snapshotId,
-            project: this.project.id,
-            location: getNodeId(nodeOrNodes),
+            project: this.project.handle,
+            location: getNodeRequestHandle(nodeOrNodes),
         });
         return data ? this.objectRegistry.getOrCreateSymbol(data) : undefined;
     }
@@ -1714,7 +1733,7 @@ export class Checker {
         if (typeof positionOrPositions === "number") {
             const data = await this.client.apiRequest("getSymbolAtPosition", {
                 snapshot: this.snapshotId,
-                project: this.project.id,
+                project: this.project.handle,
                 file,
                 position: positionOrPositions,
             });
@@ -1722,7 +1741,7 @@ export class Checker {
         }
         const data = await this.client.apiRequest("getSymbolsAtPositions", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             file,
             positions: positionOrPositions,
         });
@@ -1732,14 +1751,14 @@ export class Checker {
         if (Array.isArray(fileOrFiles)) {
             const data = await this.client.apiRequest("getSymbolsOfSourceFiles", {
                 snapshot: this.snapshotId,
-                project: this.project.id,
+                project: this.project.handle,
                 files: fileOrFiles,
             });
             return data.map(d => d ? this.objectRegistry.getOrCreateSymbol(d) : undefined);
         }
         const data = await this.client.apiRequest("getSymbolOfSourceFile", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             file: fileOrFiles,
         });
         return data ? this.objectRegistry.getOrCreateSymbol(data) : undefined;
@@ -1748,14 +1767,14 @@ export class Checker {
         if (Array.isArray(symbolOrSymbols)) {
             const data = await this.client.apiRequest("getTypesOfSymbols", {
                 snapshot: this.snapshotId,
-                project: this.project.id,
+                project: this.project.handle,
                 symbols: symbolOrSymbols.map(symbol => symbol.reference),
             });
             return data.map(d => this.objectRegistry.getOrCreateType(d));
         }
         const data = await this.client.apiRequest("getTypeOfSymbol", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             symbol: symbolOrSymbols.reference,
         });
         return this.objectRegistry.getOrCreateType(data);
@@ -1768,7 +1787,7 @@ export class Checker {
     async getDeclaredTypeOfSymbol(symbol) {
         const data = await this.client.apiRequest("getDeclaredTypeOfSymbol", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             symbol: symbol.reference,
         });
         return this.objectRegistry.getOrCreateType(data);
@@ -1782,7 +1801,7 @@ export class Checker {
     async getNonMissingTypeOfSymbol(symbol) {
         const data = await this.client.apiRequest("getNonMissingTypeOfSymbol", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             symbol: symbol.reference,
         });
         return this.objectRegistry.getOrCreateType(data);
@@ -1790,25 +1809,25 @@ export class Checker {
     async getReferencesToSymbolInFile(file, symbol) {
         const data = await this.client.apiRequest("getReferencesToSymbolInFile", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             file,
             symbol: symbol.reference,
         });
-        return (data ?? []).map(h => new NodeHandle(h, this.project));
+        return (data ?? []).map(h => this.objectRegistry.createNodeHandle(h));
     }
     async getTypeAtLocation(nodeOrNodes) {
         if (Array.isArray(nodeOrNodes)) {
             const data = await this.client.apiRequest("getTypeAtLocations", {
                 snapshot: this.snapshotId,
-                project: this.project.id,
-                locations: nodeOrNodes.map(node => getNodeId(node)),
+                project: this.project.handle,
+                locations: nodeOrNodes.map(node => getNodeRequestHandle(node)),
             });
             return data.map(d => this.objectRegistry.getOrCreateType(d));
         }
         const data = await this.client.apiRequest("getTypeAtLocation", {
             snapshot: this.snapshotId,
-            project: this.project.id,
-            location: getNodeId(nodeOrNodes),
+            project: this.project.handle,
+            location: getNodeRequestHandle(nodeOrNodes),
         });
         return this.objectRegistry.getOrCreateType(data);
     }
@@ -1823,8 +1842,8 @@ export class Checker {
     async getResolvedSignature(node) {
         const data = await this.client.apiRequest("getResolvedSignature", {
             snapshot: this.snapshotId,
-            project: this.project.id,
-            location: getNodeId(node),
+            project: this.project.handle,
+            location: getNodeRequestHandle(node),
         });
         return this.objectRegistry.getOrCreateSignature(data);
     }
@@ -1832,7 +1851,7 @@ export class Checker {
         if (typeof positionOrPositions === "number") {
             const data = await this.client.apiRequest("getTypeAtPosition", {
                 snapshot: this.snapshotId,
-                project: this.project.id,
+                project: this.project.handle,
                 file,
                 position: positionOrPositions,
             });
@@ -1840,7 +1859,7 @@ export class Checker {
         }
         const data = await this.client.apiRequest("getTypesAtPositions", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             file,
             positions: positionOrPositions,
         });
@@ -1851,10 +1870,10 @@ export class Checker {
         const isNode = location && "kind" in location;
         const data = await this.client.apiRequest("resolveName", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             name,
             meaning,
-            location: isNode ? getNodeId(location) : undefined,
+            location: isNode ? getNodeRequestHandle(location) : undefined,
             file: !isNode && location ? location.document : undefined,
             position: !isNode && location ? location.position : undefined,
             excludeGlobals,
@@ -1869,9 +1888,9 @@ export class Checker {
         const isNode = "kind" in location;
         const data = await this.client.apiRequest("getSymbolsInScope", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             meaning,
-            location: isNode ? getNodeId(location) : undefined,
+            location: isNode ? getNodeRequestHandle(location) : undefined,
             file: isNode ? undefined : location.document,
             position: isNode ? undefined : location.position,
         });
@@ -1886,16 +1905,16 @@ export class Checker {
     async getContextualType(node) {
         const data = await this.client.apiRequest("getContextualType", {
             snapshot: this.snapshotId,
-            project: this.project.id,
-            location: getNodeId(node),
+            project: this.project.handle,
+            location: getNodeRequestHandle(node),
         });
         return data ? this.objectRegistry.getOrCreateType(data) : undefined;
     }
     async getContextualTypeForArgumentAtIndex(node, argIndex) {
         const data = await this.client.apiRequest("getContextualTypeForArgument", {
             snapshot: this.snapshotId,
-            project: this.project.id,
-            location: getNodeId(node),
+            project: this.project.handle,
+            location: getNodeRequestHandle(node),
             index: argIndex,
         });
         return data ? this.objectRegistry.getOrCreateType(data) : undefined;
@@ -1903,7 +1922,7 @@ export class Checker {
     async getAwaitedType(type) {
         const data = await this.client.apiRequest("getAwaitedType", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             type: type.id,
         });
         return data ? this.objectRegistry.getOrCreateType(data) : undefined;
@@ -1912,7 +1931,7 @@ export class Checker {
     async getBaseTypeOfLiteralType(type) {
         const data = await this.client.apiRequest("getBaseTypeOfLiteralType", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             type: type.id,
         });
         return this.objectRegistry.getOrCreateType(data);
@@ -1929,8 +1948,8 @@ export class Checker {
     async getTypeFromTypeNode(node) {
         const data = await this.client.apiRequest("getTypeFromTypeNode", {
             snapshot: this.snapshotId,
-            project: this.project.id,
-            location: getNodeId(node),
+            project: this.project.handle,
+            location: getNodeRequestHandle(node),
         });
         return this.objectRegistry.getOrCreateType(data);
     }
@@ -1938,7 +1957,7 @@ export class Checker {
     async getWidenedType(type) {
         const data = await this.client.apiRequest("getWidenedType", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             type: type.id,
         });
         return this.objectRegistry.getOrCreateType(data);
@@ -1950,7 +1969,7 @@ export class Checker {
     async getParameterType(signature, index) {
         const data = await this.client.apiRequest("getParameterType", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             signature: signature.id,
             index,
         });
@@ -1959,14 +1978,14 @@ export class Checker {
     async isArrayLikeType(type) {
         return this.client.apiRequest("isArrayLikeType", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             type: type.id,
         });
     }
     async isTypeAssignableTo(source, target) {
         return this.client.apiRequest("isTypeAssignableTo", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             source: source.id,
             target: target.id,
         });
@@ -1974,8 +1993,8 @@ export class Checker {
     async getShorthandAssignmentValueSymbol(node) {
         const data = await this.client.apiRequest("getShorthandAssignmentValueSymbol", {
             snapshot: this.snapshotId,
-            project: this.project.id,
-            location: getNodeId(node),
+            project: this.project.handle,
+            location: getNodeRequestHandle(node),
         });
         return data ? this.objectRegistry.getOrCreateSymbol(data) : undefined;
     }
@@ -1987,16 +2006,16 @@ export class Checker {
     async getTypeOfSymbolAtLocation(symbol, location) {
         const data = await this.client.apiRequest("getTypeOfSymbolAtLocation", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             symbol: symbol.reference,
-            location: getNodeId(location),
+            location: getNodeRequestHandle(location),
         });
         return this.objectRegistry.getOrCreateType(data);
     }
     async getIntrinsicType(method) {
         const data = await this.client.apiRequest(method, {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
         });
         return this.objectRegistry.getOrCreateType(data);
     }
@@ -2039,9 +2058,9 @@ export class Checker {
     async typeToTypeNode(type, enclosingDeclaration, flags) {
         const binaryData = await this.client.apiRequestBinary("typeToTypeNode", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             type: type.id,
-            location: enclosingDeclaration ? getNodeId(enclosingDeclaration) : undefined,
+            location: enclosingDeclaration ? getNodeRequestHandle(enclosingDeclaration) : undefined,
             flags,
         });
         if (!binaryData)
@@ -2051,10 +2070,10 @@ export class Checker {
     async signatureToSignatureDeclaration(signature, kind, enclosingDeclaration, flags) {
         const binaryData = await this.client.apiRequestBinary("signatureToSignatureDeclaration", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             signature: signature.id,
             kind,
-            location: enclosingDeclaration ? getNodeId(enclosingDeclaration) : undefined,
+            location: enclosingDeclaration ? getNodeRequestHandle(enclosingDeclaration) : undefined,
             flags,
         });
         if (!binaryData)
@@ -2064,9 +2083,9 @@ export class Checker {
     async typeToString(type, enclosingDeclaration, flags) {
         const result = await this.client.apiRequest("typeToString", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             type: type.id,
-            location: enclosingDeclaration ? getNodeId(enclosingDeclaration) : undefined,
+            location: enclosingDeclaration ? getNodeRequestHandle(enclosingDeclaration) : undefined,
             flags,
         });
         if (typeof result !== "string")
@@ -2076,14 +2095,14 @@ export class Checker {
     async isContextSensitive(node) {
         return this.client.apiRequest("isContextSensitive", {
             snapshot: this.snapshotId,
-            project: this.project.id,
-            location: getNodeId(node),
+            project: this.project.handle,
+            location: getNodeRequestHandle(node),
         });
     }
     async isArrayType(type) {
         return this.client.apiRequest("isArrayType", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             type: type.id,
         });
     }
@@ -2105,7 +2124,7 @@ export class Checker {
     async isReadonlySymbol(symbol) {
         return this.client.apiRequest("isReadonlySymbol", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             symbol: symbol.reference,
         });
     }
@@ -2120,7 +2139,7 @@ export class Checker {
     async getRestTypeOfSignature(signature) {
         const data = await this.client.apiRequest("getRestTypeOfSignature", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             signature: signature.id,
         });
         return this.objectRegistry.getOrCreateType(data);
@@ -2128,7 +2147,7 @@ export class Checker {
     async getTypePredicateOfSignature(signature) {
         const data = await this.client.apiRequest("getTypePredicateOfSignature", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             signature: signature.id,
         });
         if (!data)
@@ -2164,7 +2183,7 @@ export class Checker {
     async getIndexInfoOfType(type, kind) {
         const data = await this.client.apiRequest("getIndexInfoOfType", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             type: type.id,
             kind,
         });
@@ -2172,7 +2191,7 @@ export class Checker {
             keyType: this.objectRegistry.getOrCreateType(data.keyType),
             valueType: this.objectRegistry.getOrCreateType(data.valueType),
             isReadonly: data.isReadonly ?? false,
-            declaration: data.declaration ? new NodeHandle(data.declaration, this.project) : undefined,
+            declaration: data.declaration ? this.objectRegistry.createNodeHandle(data.declaration) : undefined,
         } : undefined;
     }
     async getIndexTypeOfType(type, kind) {
@@ -2181,7 +2200,7 @@ export class Checker {
     async getTypeOfPropertyOfType(type, propertyName) {
         const data = await this.client.apiRequest("getTypeOfPropertyOfType", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             type: type.id,
             name: propertyName,
         });
@@ -2200,7 +2219,7 @@ export class Checker {
     async getBaseConstraintOfType(type) {
         const data = await this.client.apiRequest("getBaseConstraintOfType", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             type: type.id,
         });
         return data ? this.objectRegistry.getOrCreateType(data) : undefined;
@@ -2208,7 +2227,7 @@ export class Checker {
     async getPropertyOfType(type, name) {
         const data = await this.client.apiRequest("getPropertyOfType", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             type: type.id,
             name,
         });
@@ -2217,8 +2236,8 @@ export class Checker {
     async getConstantValue(node) {
         const data = await this.client.apiRequest("getConstantValue", {
             snapshot: this.snapshotId,
-            project: this.project.id,
-            location: getNodeId(node),
+            project: this.project.handle,
+            location: getNodeRequestHandle(node),
         });
         if (!data || (typeof data.value !== "string" && typeof data.value !== "number")) {
             return undefined;
@@ -2238,16 +2257,16 @@ export class Checker {
     async getSignatureFromDeclaration(node) {
         const data = await this.client.apiRequest("getSignatureFromDeclaration", {
             snapshot: this.snapshotId,
-            project: this.project.id,
-            location: getNodeId(node),
+            project: this.project.handle,
+            location: getNodeRequestHandle(node),
         });
         return this.objectRegistry.getOrCreateSignature(data);
     }
     async getExportSpecifierLocalTargetSymbol(node) {
         const data = await this.client.apiRequest("getExportSpecifierLocalTargetSymbol", {
             snapshot: this.snapshotId,
-            project: this.project.id,
-            location: getNodeId(node),
+            project: this.project.handle,
+            location: getNodeRequestHandle(node),
         });
         return data ? this.objectRegistry.getOrCreateSymbol(data) : undefined;
     }
@@ -2259,7 +2278,7 @@ export class Checker {
     async getAliasedSymbol(symbol) {
         const data = await this.client.apiRequest("getAliasedSymbol", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             symbol: symbol.reference,
         });
         return this.objectRegistry.getOrCreateSymbol(data);
@@ -2271,14 +2290,14 @@ export class Checker {
     async getFullyQualifiedName(symbol) {
         return this.client.apiRequest("getFullyQualifiedName", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             symbol: symbol.reference,
         });
     }
     async getImmediateAliasedSymbol(symbol) {
         const data = await this.client.apiRequest("getImmediateAliasedSymbol", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             symbol: symbol.reference,
         });
         return data ? this.objectRegistry.getOrCreateSymbol(data) : undefined;
@@ -2290,7 +2309,7 @@ export class Checker {
         if (symbol.checkFlags & CheckFlags.Instantiated) {
             const data = await this.client.apiRequest("getTargetSymbol", {
                 snapshot: this.snapshotId,
-                project: this.project.id,
+                project: this.project.handle,
                 symbol: symbol.reference,
             });
             return this.objectRegistry.getOrCreateSymbol(data);
@@ -2300,7 +2319,7 @@ export class Checker {
     async getExportSymbolOfSymbol(symbol) {
         const data = await this.client.apiRequest("getExportSymbolOfSymbolForChecker", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             symbol: symbol.reference,
         });
         return this.objectRegistry.getOrCreateSymbol(data);
@@ -2314,7 +2333,7 @@ export class Checker {
     getWellKnownSymbols() {
         return this.wellKnownSymbols ??= this.client.apiRequest("getWellKnownSymbols", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
         });
     }
     /**
@@ -2344,7 +2363,7 @@ export class Checker {
     getWellKnownSignatures() {
         return this.wellKnownSignatures ??= this.client.apiRequest("getWellKnownSignatures", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
         });
     }
     /**
@@ -2358,7 +2377,7 @@ export class Checker {
     async getExportsOfModule(symbol) {
         const data = await this.client.apiRequest("getExportsOfModule", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             symbol: symbol.reference,
         });
         return data ? data.map(d => this.objectRegistry.getOrCreateSymbol(d)) : [];
@@ -2366,7 +2385,7 @@ export class Checker {
     async getMemberInModuleExports(symbol, name) {
         const data = await this.client.apiRequest("getMemberInModuleExports", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             symbol: symbol.reference,
             name,
         });
@@ -2375,7 +2394,7 @@ export class Checker {
     async getJsDocTagsOfSymbol(symbol) {
         const data = await this.client.apiRequest("getJsDocTags", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             symbol: symbol.reference,
         });
         return data ?? [];
@@ -2383,7 +2402,7 @@ export class Checker {
     async getDocumentationCommentOfSymbol(symbol) {
         return this.client.apiRequest("getDocumentationComment", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             symbol: symbol.reference,
         });
     }
@@ -2393,7 +2412,7 @@ export class Checker {
     async getTypeArguments(type) {
         const data = await this.client.apiRequest("getTypeArguments", {
             snapshot: this.snapshotId,
-            project: this.project.id,
+            project: this.project.handle,
             type: type.id,
         });
         return data ? data.map(d => this.objectRegistry.getOrCreateType(d)) : [];
@@ -2427,7 +2446,7 @@ export class Printer {
 }
 export class NodeHandle {
     /**
-     * The project this handle was produced in, used as the default for {@link resolve}.
+     * The project where this handle was first materialized, used as the default for {@link resolve}.
      * Node handles are only meaningful within a project's program, so the producing project
      * is remembered so callers don't have to pass it explicitly.
      */
@@ -2436,11 +2455,15 @@ export class NodeHandle {
     fileOwner;
     index;
     kind;
+    /** Identity of the exact parsed source file, shared across programs that reuse that AST. */
+    sourceFileId;
+    /** Retrieval metadata; never used to substitute a different source-file AST. */
     path;
     constructor(handle, canonicalProject, fileOwner) {
         const parsed = parseNodeHandleFromCompiler(handle);
         this.index = parsed.index;
         this.kind = parsed.kind;
+        this.sourceFileId = parsed.sourceFileId;
         this.path = parsed.path;
         this.canonicalProject = canonicalProject;
         this.fileOwner = fileOwner;
@@ -2449,20 +2472,31 @@ export class NodeHandle {
      * Resolve this handle to the actual AST node by fetching the source file from a project
      * and looking up the node by index. If no project is passed, the project that produced
      * the handle is used. Declarations of file-owned symbols identify an exact source file and
-     * resolve through it, independently of any project.
+     * resolve through it, independently of any project. A different AST at the
+     * same path is never substituted.
      */
     async resolve(project = this.canonicalProject) {
         if (this.fileOwner) {
             const sourceFile = this.fileOwner.record.file ?? await this.fetchOwnerFile(this.fileOwner);
-            return sourceFile.getOrCreateNodeAtIndex(this.index);
+            return this.resolveInFile(sourceFile);
         }
         if (!project)
-            throw new Error(`Node handle for '${this.path}' has no project context`);
+            throw new Error(`Node handle for source file '${this.sourceFileId}' has no project context`);
         const sourceFile = await project.program.getSourceFileByPath(this.path);
         if (!sourceFile) {
-            return undefined;
+            throw new Error("Node handle source file is not part of the requested program");
         }
-        return sourceFile.getOrCreateNodeAtIndex(this.index);
+        return this.resolveInFile(sourceFile);
+    }
+    resolveInFile(sourceFile) {
+        if (sourceFile.nodeId !== this.sourceFileId) {
+            throw new Error(`Node handle source file is not part of the requested program`);
+        }
+        const node = sourceFile.getOrCreateNodeAtIndex(this.index);
+        if (!node || node.kind !== this.kind) {
+            throw new Error("Node handle does not identify a node of the expected kind");
+        }
+        return node;
     }
     async fetchOwnerFile(fileOwner) {
         const data = await fileOwner.api.client.apiRequestBinary("getCachedSourceFile", { file: fileOwner.record.descriptor });
@@ -2484,8 +2518,11 @@ export class Symbol {
     checkFlags;
     /** @internal */
     reference;
-    declarations;
-    valueDeclaration;
+    // Declaration handles are kept in their wire form until first accessed.
+    declarationHandles;
+    valueDeclarationHandle;
+    declarationsCache;
+    valueDeclarationCache;
     parent;
     exportSymbol;
     membersCache;
@@ -2498,19 +2535,31 @@ export class Symbol {
         this.escapedName = data.name;
         this.name = unescapeLeadingUnderscores(data.name);
         this.flags = data.flags;
-        this.checkFlags = data.checkFlags;
-        // A file-owned symbol has no canonical project; its declarations resolve through its file.
-        const project = storage.kind === SymbolOwnerKind.Snapshot ? storage.registry.project : undefined;
-        const fileOwner = storage.kind === SymbolOwnerKind.File ? storage.owner : undefined;
-        this.declarations = (data.declarations ?? []).map(handle => new NodeHandle(handle, project, fileOwner));
-        this.valueDeclaration = data.valueDeclaration
-            ? new NodeHandle(data.valueDeclaration, project, fileOwner)
-            : undefined;
+        this.checkFlags = data.checkFlags ?? 0;
+        this.declarationHandles = data.declarations;
+        this.valueDeclarationHandle = data.valueDeclaration;
+        this.declarationsCache = undefined;
+        this.valueDeclarationCache = undefined;
         if (data.parent !== undefined)
             this.parent = data.parent;
         if (data.exportSymbol !== undefined)
             this.exportSymbol = data.exportSymbol;
     }
+    get declarations() {
+        return this.declarationsCache ??= this.declarationHandles?.map(handle => this.createDeclarationHandle(handle)) ?? [];
+    }
+    get valueDeclaration() {
+        if (this.valueDeclarationCache === undefined && this.valueDeclarationHandle) {
+            this.valueDeclarationCache = this.createDeclarationHandle(this.valueDeclarationHandle);
+        }
+        return this.valueDeclarationCache;
+    }
+    createDeclarationHandle(handle) {
+        // A file-owned symbol has no canonical project; its declarations resolve through its file.
+        return this.storage.kind === SymbolOwnerKind.Snapshot
+            ? this.storage.registry.createNodeHandle(handle)
+            : new NodeHandle(handle, undefined, this.storage.owner);
+    }
     async getParent() {
         if (!this.parent)
             return undefined;
@@ -2640,8 +2689,7 @@ class TypeObject {
         this.objectRegistry = objectRegistry;
         this.id = data.id;
         this.flags = data.flags;
-        if (data.objectFlags !== undefined)
-            this.objectFlags = data.objectFlags;
+        this.objectFlags = data.objectFlags ?? 0;
         if (data.symbol !== undefined)
             this.symbol = data.symbol;
         if (data.value != null) {
@@ -2669,8 +2717,7 @@ class TypeObject {
         }
         if (data.intrinsicName !== undefined)
             this.intrinsicName = data.intrinsicName;
-        if (data.isThisType !== undefined)
-            this.isThisType = data.isThisType;
+        this.isThisType = data.isThisType ?? false;
         if (data.freshType !== undefined)
             this.freshType = data.freshType;
         if (data.regularType !== undefined)
@@ -3049,7 +3096,9 @@ export class Signature {
     flags;
     objectRegistry;
     id;
-    declaration;
+    project;
+    declarationHandle;
+    declarationCache;
     typeParameters;
     parameters;
     thisParameter;
@@ -3057,15 +3106,23 @@ export class Signature {
     returnType;
     constructor(data, project, objectRegistry) {
         this.id = data.id;
-        this.flags = data.flags;
+        this.flags = data.flags ?? 0;
         this.objectRegistry = objectRegistry;
-        this.declaration = data.declaration ? new NodeHandle(data.declaration, project) : undefined;
+        this.project = project;
+        this.declarationHandle = data.declaration;
+        this.declarationCache = undefined;
         this.typeParameters = data.typeParameters ?? [];
         this.parameters = data.parameters ?? [];
         this.thisParameter = data.thisParameter;
         this.target = data.target;
         this.returnType = false;
     }
+    get declaration() {
+        if (this.declarationCache === undefined && this.declarationHandle) {
+            this.declarationCache = this.objectRegistry.createNodeHandle(this.declarationHandle);
+        }
+        return this.declarationCache;
+    }
     async getTypeParameters() {
         return this.objectRegistry.fetchTypes(this, "getTypeParametersOfSignature", this.typeParameters);
     }