typescript 7.1.0-dev.20260928.1 → 7.1.0-dev.20260930.4

package/dist/api/sync/api.js

@@ -15,21 +15,22 @@ import { ScriptKind } from "#enums/scriptKind";
 import { SignatureFlags } from "#enums/signatureFlags";
 import { SignatureKind } from "#enums/signatureKind";
 import { SymbolFlags } from "#enums/symbolFlags";
+import { SymbolOwnerKind } from "#enums/symbolOwnerKind";
 import { TypeFlags } from "#enums/typeFlags";
 import { TypeFormatFlags } from "#enums/typeFormatFlags";
 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, parseNodeHandle, readParseOptionsKey, readSourceFileHash, readSourceFileLease, RemoteSourceFile, } from "../node/node.js";
+import { decodeNode, getNodeId, parseNodeHandle, readSourceFileLease, RemoteSourceFile, } from "../node/node.js";
 import { Wtf8Decoder } from "../node/wtf8.js";
 import { createGetCanonicalFileName, toPath, } from "../path.js";
-import { resolveFileName, toCreateSnapshotRequest, } from "../proto.js";
-import { SourceFileCache } from "../sourceFileCache.js";
+import { resolveFileName, toCreateSnapshotRequest, validateSymbolResponse, } from "../proto.js";
+import { SourceFileCache, } from "../sourceFileCache.js";
 import { Client, } from "./client.js";
 export { formatDiagnostics, formatDiagnosticsWithColorAndContext } from "../diagnosticFormatter.js";
 export { documentURIToFileName, fileNameToDocumentURI } from "../path.js";
-export { CheckFlags, CompletionItemKind, DiagnosticCategory, ElementFlags, EmitOnly, IndexKind, JsxEmit, ModifierFlags, ModuleKind, ModuleResolutionKind, NodeBuilderFlags, ObjectFlags, ScriptKind, SignatureFlags, SignatureKind, SymbolFlags, TypeFlags, TypeFormatFlags, TypePredicateKind };
+export { CheckFlags, CompletionItemKind, DiagnosticCategory, ElementFlags, EmitOnly, IndexKind, JsxEmit, ModifierFlags, ModuleKind, ModuleResolutionKind, NodeBuilderFlags, ObjectFlags, ScriptKind, SignatureFlags, SignatureKind, SymbolFlags, SymbolOwnerKind, TypeFlags, TypeFormatFlags, TypePredicateKind };
 let nextModuleResolutionCallbackId = 0;
 function registerModuleResolutionCallback(client, callback, getSnapshot) {
     const name = `resolveModuleName/${++nextModuleResolutionCallbackId}`;
@@ -259,18 +260,41 @@ export class API {
             return owner.retainSourceFileResponse(data);
         });
     }
+    /**
+     * Retain an ordinary remote source file independently of the snapshot or lease that produced it.
+     */
+    get retainSourceFile() {
+        const owner = this;
+        return cacheGeneratorMethod(owner, "retainSourceFile", function (sourceFile) {
+            owner.ensureInitialized();
+            if (!(sourceFile instanceof RemoteSourceFile)) {
+                throw new TypeError("Only remote source files can be retained");
+            }
+            const cached = owner.sourceFileCache.get(sourceFile);
+            if (cached && cached !== sourceFile) {
+                throw new Error("Source file is no longer the canonical cached instance");
+            }
+            const result = owner.client.apiRequest("retainSourceFile", { file: sourceFileDescriptor(sourceFile) });
+            return owner.addSourceFileLease(sourceFile, result.lease);
+        }, function* (sourceFile) {
+            yield* owner.ensureInitialized.gen();
+            if (!(sourceFile instanceof RemoteSourceFile)) {
+                throw new TypeError("Only remote source files can be retained");
+            }
+            const cached = owner.sourceFileCache.get(sourceFile);
+            if (cached && cached !== sourceFile) {
+                throw new Error("Source file is no longer the canonical cached instance");
+            }
+            const result = yield* apiRequest("retainSourceFile", { file: sourceFileDescriptor(sourceFile) });
+            return owner.addSourceFileLease(sourceFile, result.lease);
+        });
+    }
     retainSourceFileResponse(data) {
         const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
         const lease = readSourceFileLease(view);
         try {
             const decoded = new RemoteSourceFile(data, this.decoder, this.client.getTimingCollector());
-            const sourceFile = this.sourceFileCache.setForLease(decoded.path, decoded, readParseOptionsKey(view), readSourceFileHash(view), lease);
-            const retained = new RetainedSourceFile(sourceFile, lease, this.client, () => {
-                this.activeSourceFileLeases.delete(lease);
-                this.sourceFileCache.releaseLease(lease);
-            });
-            this.activeSourceFileLeases.set(lease, retained);
-            return retained;
+            return this.addSourceFileLease(decoded, lease);
         }
         catch (error) {
             try {
@@ -280,6 +304,15 @@ export class API {
             throw error;
         }
     }
+    addSourceFileLease(sourceFile, lease) {
+        const cached = this.sourceFileCache.setForLease(sourceFile, lease);
+        const retained = new RetainedSourceFile(cached, lease, this.client, () => {
+            this.activeSourceFileLeases.delete(lease);
+            this.sourceFileCache.releaseLease(lease);
+        });
+        this.activeSourceFileLeases.set(lease, retained);
+        return retained;
+    }
     get transpileModule() {
         const owner = this;
         return cacheGeneratorMethod(owner, "transpileModule", function (input, options = {}) {
@@ -659,6 +692,16 @@ export class API {
         });
     }
 }
+function sourceFileDescriptor(sourceFile) {
+    return {
+        fileName: sourceFile.fileName,
+        path: sourceFile.path,
+        contentHash: sourceFile.contentHash,
+        parseOptionsKey: sourceFile.parseOptionsKey,
+        scriptKind: sourceFile.scriptKind,
+        nodeId: sourceFile.nodeId,
+    };
+}
 /** An independently retained source file and its disposable remote-lifetime lease. */
 export class RetainedSourceFile {
     sourceFile;
@@ -780,7 +823,7 @@ export class Snapshot {
             projectDataMap.set(projectData.id, projectData);
         }
         this.projectDataMap = new Map([...projectDataMap].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0));
-        this.snapshotRegistry = new SnapshotObjectRegistry(client, this.id, projectId => this.projectMap.get(projectId));
+        this.snapshotRegistry = new SnapshotObjectRegistry(this.id);
         for (const projData of this.projectDataMap.values()) {
             const project = new Project(projData, this.id, client, sourceFileCache, toPath, formatDiagnosticsHost, this.snapshotRegistry);
             this.projectMap.set(projData.id, project);
@@ -974,23 +1017,28 @@ export class ModuleResolver {
 }
 class SnapshotObjectRegistry {
     symbols = new Map();
-    client;
+    projectRegistries = new Map();
     snapshotId;
-    resolveProject;
-    constructor(client, snapshotId, resolveProject) {
-        this.client = client;
+    constructor(snapshotId) {
         this.snapshotId = snapshotId;
-        this.resolveProject = resolveProject;
     }
-    /** Resolve a project ID to its Project within this snapshot. */
-    getProject(projectId) {
-        return this.resolveProject(projectId);
+    addProjectRegistry(registry) {
+        this.projectRegistries.set(registry.project.id, registry);
     }
     getOrCreateSymbol(data) {
-        let symbol = this.symbols.get(data.id);
+        const reference = data.reference;
+        if (reference.kind !== SymbolOwnerKind.Snapshot)
+            throw new Error(`Symbol ${reference.id} is not snapshot-owned`);
+        let symbol = this.symbols.get(reference.id);
         if (!symbol) {
-            symbol = new Symbol(data, this);
-            this.symbols.set(data.id, symbol);
+            if (reference.snapshot !== this.snapshotId) {
+                throw new Error(`Symbol ${reference.id} belongs to snapshot ${reference.snapshot}, not ${this.snapshotId}`);
+            }
+            const registry = this.projectRegistries.get(reference.project);
+            if (!registry)
+                throw new Error(`Symbol ${reference.id} references unknown project '${reference.project}'`);
+            symbol = new Symbol(data, { kind: SymbolOwnerKind.Snapshot, registry });
+            this.symbols.set(reference.id, symbol);
         }
         return symbol;
     }
@@ -1000,109 +1048,49 @@ class SnapshotObjectRegistry {
     clear() {
         this.symbols.clear();
     }
-    get fetchSymbol() {
-        const owner = this;
-        return cacheGeneratorMethod(owner, "fetchSymbol", function (source, method, handle, projectId) {
-            if (!handle)
-                return undefined;
-            const cached = owner.getSymbol(handle);
-            if (cached)
-                return cached;
-            const data = owner.client.apiRequest(method, {
-                snapshot: owner.snapshotId,
-                project: projectId,
-                objectId: source.id,
-            });
-            if (!data)
-                throw new Error(`${method} returned null symbol for ${source.constructor.name} ${source.id}`);
-            return owner.getOrCreateSymbol(data);
-        }, function* (source, method, handle, projectId) {
-            if (!handle)
-                return undefined;
-            const cached = owner.getSymbol(handle);
-            if (cached)
-                return cached;
-            const data = yield* apiRequest(method, {
-                snapshot: owner.snapshotId,
-                project: projectId,
-                objectId: source.id,
-            });
-            if (!data)
-                throw new Error(`${method} returned null symbol for ${source.constructor.name} ${source.id}`);
-            return owner.getOrCreateSymbol(data);
-        });
-    }
-    get fetchSymbols() {
-        const owner = this;
-        return cacheGeneratorMethod(owner, "fetchSymbols", function (source, method, handles, projectId) {
-            if (handles) {
-                const result = new Array(handles.length);
-                let allCached = true;
-                for (let i = 0; i < handles.length; i++) {
-                    const cached = owner.getSymbol(handles[i]);
-                    if (!cached) {
-                        allCached = false;
-                        break;
-                    }
-                    result[i] = cached;
-                }
-                if (allCached)
-                    return result;
-            }
-            const symbolData = owner.client.apiRequest(method, {
-                snapshot: owner.snapshotId,
-                project: projectId,
-                objectId: source.id,
-            });
-            if (symbolData == null)
-                return [];
-            else
-                return symbolData.map(data => owner.getOrCreateSymbol(data));
-        }, function* (source, method, handles, projectId) {
-            if (handles) {
-                const result = new Array(handles.length);
-                let allCached = true;
-                for (let i = 0; i < handles.length; i++) {
-                    const cached = owner.getSymbol(handles[i]);
-                    if (!cached) {
-                        allCached = false;
-                        break;
-                    }
-                    result[i] = cached;
-                }
-                if (allCached)
-                    return result;
-            }
-            const symbolData = yield* apiRequest(method, {
-                snapshot: owner.snapshotId,
-                project: projectId,
-                objectId: source.id,
-            });
-            if (symbolData == null)
-                return [];
-            else
-                return symbolData.map(data => owner.getOrCreateSymbol(data));
-        });
-    }
 }
 class ProjectObjectRegistry {
     client;
     snapshotId;
     project;
     snapshotRegistry;
+    sourceFileCache;
     types = new Map();
     signatures = new Map();
-    constructor(client, snapshotId, project, snapshotRegistry) {
+    disposed = false;
+    constructor(client, snapshotId, project, snapshotRegistry, sourceFileCache) {
         this.client = client;
         this.snapshotId = snapshotId;
         this.project = project;
         this.snapshotRegistry = snapshotRegistry;
+        this.sourceFileCache = sourceFileCache;
+        snapshotRegistry.addProjectRegistry(this);
     }
     getOrCreateSymbol(data) {
-        return this.snapshotRegistry.getOrCreateSymbol(data);
-    }
-    getSymbol(id) {
-        return this.snapshotRegistry.getSymbol(id);
+        this.ensureNotDisposed();
+        validateSymbolResponse(data);
+        const reference = data.reference;
+        if (reference.kind === SymbolOwnerKind.Snapshot) {
+            return this.snapshotRegistry.getOrCreateSymbol(data);
+        }
+        const record = this.sourceFileCache.getOrCreateRecord(reference.file, this.snapshotId, this.project.id);
+        return this.sourceFileCache.getOrCreateSymbol(record, reference.file, reference.id, () => new Symbol(data, {
+            kind: SymbolOwnerKind.File,
+            owner: { record, cache: this.sourceFileCache, client: this.client },
+        }));
+    }
+    /** Find an already-interned symbol and retain its file record for this registry. */
+    getCachedSymbol(reference) {
+        this.ensureNotDisposed();
+        if (reference.file === undefined) {
+            return this.snapshotRegistry.getSymbol(reference.id);
+        }
+        const record = this.sourceFileCache.findRecord(reference.file);
+        const symbol = record?.symbols.get(reference.id);
+        if (record && symbol) {
+            this.sourceFileCache.retainRecord(record, this.snapshotId, this.project.id);
+        }
+        return symbol;
     }
     getOrCreateType(data) {
         let type = this.types.get(data.id);
@@ -1130,9 +1118,14 @@ class ProjectObjectRegistry {
         return this.signatures.get(id);
     }
     clear() {
+        this.disposed = true;
         this.types.clear();
         this.signatures.clear();
     }
+    ensureNotDisposed() {
+        if (this.disposed)
+            throw new Error("Project object registry is disposed");
+    }
     get fetchOptionalType() {
         const owner = this;
         return cacheGeneratorMethod(owner, "fetchOptionalType", function (source, method, handle) {
@@ -1185,10 +1178,38 @@ class ProjectObjectRegistry {
     }
     get fetchSymbol() {
         const owner = this;
-        return cacheGeneratorMethod(owner, "fetchSymbol", function (source, method, handle) {
-            return owner.snapshotRegistry.fetchSymbol(source, method, handle, owner.project.id);
-        }, function* (source, method, handle) {
-            return yield* owner.snapshotRegistry.fetchSymbol.gen(source, method, handle, owner.project.id);
+        return cacheGeneratorMethod(owner, "fetchSymbol", function (source, method, reference) {
+            if (!reference)
+                return undefined;
+            const cached = owner.getCachedSymbol(reference);
+            if (cached)
+                return cached;
+            const data = source instanceof Symbol
+                ? owner.client.apiRequest(method, { symbol: source.reference })
+                : owner.client.apiRequest(method, {
+                    snapshot: owner.snapshotId,
+                    project: owner.project.id,
+                    objectId: source.id,
+                });
+            if (!data)
+                throw new Error(`${method} returned null symbol for ${source.constructor.name} ${source.id}`);
+            return owner.getOrCreateSymbol(data);
+        }, function* (source, method, reference) {
+            if (!reference)
+                return undefined;
+            const cached = owner.getCachedSymbol(reference);
+            if (cached)
+                return cached;
+            const data = source instanceof Symbol
+                ? yield* apiRequest(method, { symbol: source.reference })
+                : yield* apiRequest(method, {
+                    snapshot: owner.snapshotId,
+                    project: owner.project.id,
+                    objectId: source.id,
+                });
+            if (!data)
+                throw new Error(`${method} returned null symbol for ${source.constructor.name} ${source.id}`);
+            return owner.getOrCreateSymbol(data);
         });
     }
     get fetchSignature() {
@@ -1277,10 +1298,54 @@ class ProjectObjectRegistry {
     }
     get fetchSymbols() {
         const owner = this;
-        return cacheGeneratorMethod(owner, "fetchSymbols", function (source, method, handles) {
-            return owner.snapshotRegistry.fetchSymbols(source, method, handles, owner.project.id);
-        }, function* (source, method, handles) {
-            return yield* owner.snapshotRegistry.fetchSymbols.gen(source, method, handles, owner.project.id);
+        return cacheGeneratorMethod(owner, "fetchSymbols", function (source, method, references) {
+            if (references) {
+                const result = new Array(references.length);
+                for (let i = 0; i < references.length; i++) {
+                    const cached = owner.getCachedSymbol(references[i]);
+                    if (!cached) {
+                        return owner.fetchSymbolsFromServer(source, method);
+                    }
+                    result[i] = cached;
+                }
+                return result;
+            }
+            return owner.fetchSymbolsFromServer(source, method);
+        }, function* (source, method, references) {
+            if (references) {
+                const result = new Array(references.length);
+                for (let i = 0; i < references.length; i++) {
+                    const cached = owner.getCachedSymbol(references[i]);
+                    if (!cached) {
+                        return yield* owner.fetchSymbolsFromServer.gen(source, method);
+                    }
+                    result[i] = cached;
+                }
+                return result;
+            }
+            return yield* owner.fetchSymbolsFromServer.gen(source, method);
+        });
+    }
+    get fetchSymbolsFromServer() {
+        const owner = this;
+        return cacheGeneratorMethod(owner, "fetchSymbolsFromServer", function (source, method) {
+            const data = source instanceof Symbol
+                ? owner.client.apiRequest(method, { symbol: source.reference })
+                : owner.client.apiRequest(method, {
+                    snapshot: owner.snapshotId,
+                    project: owner.project.id,
+                    objectId: source.id,
+                });
+            return data?.map(symbol => owner.getOrCreateSymbol(symbol)) ?? [];
+        }, function* (source, method) {
+            const data = source instanceof Symbol
+                ? yield* apiRequest(method, { symbol: source.reference })
+                : yield* apiRequest(method, {
+                    snapshot: owner.snapshotId,
+                    project: owner.project.id,
+                    objectId: source.id,
+                });
+            return data?.map(symbol => owner.getOrCreateSymbol(symbol)) ?? [];
         });
     }
     // getBaseTypes is a checker-level endpoint keyed by `type` (not `objectId`),
@@ -1465,7 +1530,7 @@ export class Project {
         this.client = client;
         this.snapshotId = snapshotId;
         this.program = new Program(snapshotId, this, client, sourceFileCache, toPath, formatDiagnosticsHost);
-        const objectRegistry = new ProjectObjectRegistry(client, snapshotId, this, snapshotRegistry);
+        const objectRegistry = new ProjectObjectRegistry(client, snapshotId, this, snapshotRegistry, sourceFileCache);
         this.checker = new Checker(snapshotId, this, client, objectRegistry);
         this.languageService = new LanguageService(snapshotId, this, client, objectRegistry);
     }
@@ -1510,7 +1575,7 @@ export class LanguageService {
                     case "importSymbol":
                         const importSymbolAction = {
                             kind: "importSymbol",
-                            symbol: action.symbol.id,
+                            symbol: action.symbol.reference,
                         };
                         if (action.isValidTypeOnlyUseSite !== undefined) {
                             importSymbolAction.isValidTypeOnlyUseSite = action.isValidTypeOnlyUseSite;
@@ -1533,7 +1598,7 @@ export class LanguageService {
                     case "importSymbol":
                         const importSymbolAction = {
                             kind: "importSymbol",
-                            symbol: action.symbol.id,
+                            symbol: action.symbol.reference,
                         };
                         if (action.isValidTypeOnlyUseSite !== undefined) {
                             importSymbolAction.isValidTypeOnlyUseSite = action.isValidTypeOnlyUseSite;
@@ -1759,12 +1824,9 @@ export class Program {
             if (!binaryData) {
                 return undefined;
             }
-            const view = new DataView(binaryData.buffer, binaryData.byteOffset, binaryData.byteLength);
-            const contentHash = readSourceFileHash(view);
-            const parseOptionsKey = readParseOptionsKey(view);
             // Create a new RemoteSourceFile and cache it (set returns existing if hash matches)
-            const sourceFile = new RemoteSourceFile(binaryData, owner.decoder, owner.client.getTimingCollector());
-            return owner.sourceFileCache.set(path, sourceFile, parseOptionsKey, contentHash, owner.snapshotId, owner.project.id);
+            const decoded = new RemoteSourceFile(binaryData, owner.decoder, owner.client.getTimingCollector());
+            return owner.sourceFileCache.set(decoded, owner.snapshotId, owner.project.id);
         }, function* (file) {
             const fileName = resolveFileName(file);
             const path = owner.toPath(fileName);
@@ -1782,12 +1844,9 @@ export class Program {
             if (!binaryData) {
                 return undefined;
             }
-            const view = new DataView(binaryData.buffer, binaryData.byteOffset, binaryData.byteLength);
-            const contentHash = readSourceFileHash(view);
-            const parseOptionsKey = readParseOptionsKey(view);
             // Create a new RemoteSourceFile and cache it (set returns existing if hash matches)
-            const sourceFile = new RemoteSourceFile(binaryData, owner.decoder, owner.client.getTimingCollector());
-            return owner.sourceFileCache.set(path, sourceFile, parseOptionsKey, contentHash, owner.snapshotId, owner.project.id);
+            const decoded = new RemoteSourceFile(binaryData, owner.decoder, owner.client.getTimingCollector());
+            return owner.sourceFileCache.set(decoded, owner.snapshotId, owner.project.id);
         });
     }
     get getResolvedModule() {
@@ -2652,14 +2711,14 @@ export class Checker {
                 const data = owner.client.apiRequest("getTypesOfSymbols", {
                     snapshot: owner.snapshotId,
                     project: owner.project.id,
-                    symbols: symbolOrSymbols.map(s => s.id),
+                    symbols: symbolOrSymbols.map(symbol => symbol.reference),
                 });
                 return data.map(d => owner.objectRegistry.getOrCreateType(d));
             }
             const data = owner.client.apiRequest("getTypeOfSymbol", {
                 snapshot: owner.snapshotId,
                 project: owner.project.id,
-                symbol: symbolOrSymbols.id,
+                symbol: symbolOrSymbols.reference,
             });
             return owner.objectRegistry.getOrCreateType(data);
         }
@@ -2668,14 +2727,14 @@ export class Checker {
                 const data = yield* apiRequest("getTypesOfSymbols", {
                     snapshot: owner.snapshotId,
                     project: owner.project.id,
-                    symbols: symbolOrSymbols.map(s => s.id),
+                    symbols: symbolOrSymbols.map(symbol => symbol.reference),
                 });
                 return data.map(d => owner.objectRegistry.getOrCreateType(d));
             }
             const data = yield* apiRequest("getTypeOfSymbol", {
                 snapshot: owner.snapshotId,
                 project: owner.project.id,
-                symbol: symbolOrSymbols.id,
+                symbol: symbolOrSymbols.reference,
             });
             return owner.objectRegistry.getOrCreateType(data);
         }
@@ -2692,14 +2751,14 @@ export class Checker {
             const data = owner.client.apiRequest("getDeclaredTypeOfSymbol", {
                 snapshot: owner.snapshotId,
                 project: owner.project.id,
-                symbol: symbol.id,
+                symbol: symbol.reference,
             });
             return owner.objectRegistry.getOrCreateType(data);
         }, function* (symbol) {
             const data = yield* apiRequest("getDeclaredTypeOfSymbol", {
                 snapshot: owner.snapshotId,
                 project: owner.project.id,
-                symbol: symbol.id,
+                symbol: symbol.reference,
             });
             return owner.objectRegistry.getOrCreateType(data);
         });
@@ -2716,14 +2775,14 @@ export class Checker {
             const data = owner.client.apiRequest("getNonMissingTypeOfSymbol", {
                 snapshot: owner.snapshotId,
                 project: owner.project.id,
-                symbol: symbol.id,
+                symbol: symbol.reference,
             });
             return owner.objectRegistry.getOrCreateType(data);
         }, function* (symbol) {
             const data = yield* apiRequest("getNonMissingTypeOfSymbol", {
                 snapshot: owner.snapshotId,
                 project: owner.project.id,
-                symbol: symbol.id,
+                symbol: symbol.reference,
             });
             return owner.objectRegistry.getOrCreateType(data);
         });
@@ -2735,7 +2794,7 @@ export class Checker {
                 snapshot: owner.snapshotId,
                 project: owner.project.id,
                 file,
-                symbol: symbol.id,
+                symbol: symbol.reference,
             });
             return (data ?? []).map(h => new NodeHandle(h, owner.project));
         }, function* (file, symbol) {
@@ -2743,7 +2802,7 @@ export class Checker {
                 snapshot: owner.snapshotId,
                 project: owner.project.id,
                 file,
-                symbol: symbol.id,
+                symbol: symbol.reference,
             });
             return (data ?? []).map(h => new NodeHandle(h, owner.project));
         });
@@ -3177,7 +3236,7 @@ export class Checker {
             const data = owner.client.apiRequest("getTypeOfSymbolAtLocation", {
                 snapshot: owner.snapshotId,
                 project: owner.project.id,
-                symbol: symbol.id,
+                symbol: symbol.reference,
                 location: getNodeId(location),
             });
             return owner.objectRegistry.getOrCreateType(data);
@@ -3185,7 +3244,7 @@ export class Checker {
             const data = yield* apiRequest("getTypeOfSymbolAtLocation", {
                 snapshot: owner.snapshotId,
                 project: owner.project.id,
-                symbol: symbol.id,
+                symbol: symbol.reference,
                 location: getNodeId(location),
             });
             return owner.objectRegistry.getOrCreateType(data);
@@ -3446,13 +3505,13 @@ export class Checker {
             return owner.client.apiRequest("isReadonlySymbol", {
                 snapshot: owner.snapshotId,
                 project: owner.project.id,
-                symbol: symbol.id,
+                symbol: symbol.reference,
             });
         }, function* (symbol) {
             return yield* apiRequest("isReadonlySymbol", {
                 snapshot: owner.snapshotId,
                 project: owner.project.id,
-                symbol: symbol.id,
+                symbol: symbol.reference,
             });
         });
     }
@@ -3771,14 +3830,14 @@ export class Checker {
             const data = owner.client.apiRequest("getAliasedSymbol", {
                 snapshot: owner.snapshotId,
                 project: owner.project.id,
-                symbol: symbol.id,
+                symbol: symbol.reference,
             });
             return owner.objectRegistry.getOrCreateSymbol(data);
         }, function* (symbol) {
             const data = yield* apiRequest("getAliasedSymbol", {
                 snapshot: owner.snapshotId,
                 project: owner.project.id,
-                symbol: symbol.id,
+                symbol: symbol.reference,
             });
             return owner.objectRegistry.getOrCreateSymbol(data);
         });
@@ -3793,13 +3852,13 @@ export class Checker {
             return owner.client.apiRequest("getFullyQualifiedName", {
                 snapshot: owner.snapshotId,
                 project: owner.project.id,
-                symbol: symbol.id,
+                symbol: symbol.reference,
             });
         }, function* (symbol) {
             return yield* apiRequest("getFullyQualifiedName", {
                 snapshot: owner.snapshotId,
                 project: owner.project.id,
-                symbol: symbol.id,
+                symbol: symbol.reference,
             });
         });
     }
@@ -3809,14 +3868,14 @@ export class Checker {
             const data = owner.client.apiRequest("getImmediateAliasedSymbol", {
                 snapshot: owner.snapshotId,
                 project: owner.project.id,
-                symbol: symbol.id,
+                symbol: symbol.reference,
             });
             return data ? owner.objectRegistry.getOrCreateSymbol(data) : undefined;
         }, function* (symbol) {
             const data = yield* apiRequest("getImmediateAliasedSymbol", {
                 snapshot: owner.snapshotId,
                 project: owner.project.id,
-                symbol: symbol.id,
+                symbol: symbol.reference,
             });
             return data ? owner.objectRegistry.getOrCreateSymbol(data) : undefined;
         });
@@ -3831,7 +3890,7 @@ export class Checker {
                 const data = owner.client.apiRequest("getTargetSymbol", {
                     snapshot: owner.snapshotId,
                     project: owner.project.id,
-                    symbol: symbol.id,
+                    symbol: symbol.reference,
                 });
                 return owner.objectRegistry.getOrCreateSymbol(data);
             }
@@ -3841,7 +3900,7 @@ export class Checker {
                 const data = yield* apiRequest("getTargetSymbol", {
                     snapshot: owner.snapshotId,
                     project: owner.project.id,
-                    symbol: symbol.id,
+                    symbol: symbol.reference,
                 });
                 return owner.objectRegistry.getOrCreateSymbol(data);
             }
@@ -3854,14 +3913,14 @@ export class Checker {
             const data = owner.client.apiRequest("getExportSymbolOfSymbolForChecker", {
                 snapshot: owner.snapshotId,
                 project: owner.project.id,
-                symbol: symbol.id,
+                symbol: symbol.reference,
             });
             return owner.objectRegistry.getOrCreateSymbol(data);
         }, function* (symbol) {
             const data = yield* apiRequest("getExportSymbolOfSymbolForChecker", {
                 snapshot: owner.snapshotId,
                 project: owner.project.id,
-                symbol: symbol.id,
+                symbol: symbol.reference,
             });
             return owner.objectRegistry.getOrCreateSymbol(data);
         });
@@ -3958,14 +4017,14 @@ export class Checker {
             const data = owner.client.apiRequest("getExportsOfModule", {
                 snapshot: owner.snapshotId,
                 project: owner.project.id,
-                symbol: symbol.id,
+                symbol: symbol.reference,
             });
             return data ? data.map(d => owner.objectRegistry.getOrCreateSymbol(d)) : [];
         }, function* (symbol) {
             const data = yield* apiRequest("getExportsOfModule", {
                 snapshot: owner.snapshotId,
                 project: owner.project.id,
-                symbol: symbol.id,
+                symbol: symbol.reference,
             });
             return data ? data.map(d => owner.objectRegistry.getOrCreateSymbol(d)) : [];
         });
@@ -3976,7 +4035,7 @@ export class Checker {
             const data = owner.client.apiRequest("getMemberInModuleExports", {
                 snapshot: owner.snapshotId,
                 project: owner.project.id,
-                symbol: symbol.id,
+                symbol: symbol.reference,
                 name,
             });
             return data ? owner.objectRegistry.getOrCreateSymbol(data) : undefined;
@@ -3984,7 +4043,7 @@ export class Checker {
             const data = yield* apiRequest("getMemberInModuleExports", {
                 snapshot: owner.snapshotId,
                 project: owner.project.id,
-                symbol: symbol.id,
+                symbol: symbol.reference,
                 name,
             });
             return data ? owner.objectRegistry.getOrCreateSymbol(data) : undefined;
@@ -3996,14 +4055,14 @@ export class Checker {
             const data = owner.client.apiRequest("getJsDocTags", {
                 snapshot: owner.snapshotId,
                 project: owner.project.id,
-                symbol: symbol.id,
+                symbol: symbol.reference,
             });
             return data ?? [];
         }, function* (symbol) {
             const data = yield* apiRequest("getJsDocTags", {
                 snapshot: owner.snapshotId,
                 project: owner.project.id,
-                symbol: symbol.id,
+                symbol: symbol.reference,
             });
             return data ?? [];
         });
@@ -4014,13 +4073,13 @@ export class Checker {
             return owner.client.apiRequest("getDocumentationComment", {
                 snapshot: owner.snapshotId,
                 project: owner.project.id,
-                symbol: symbol.id,
+                symbol: symbol.reference,
             });
         }, function* (symbol) {
             return yield* apiRequest("getDocumentationComment", {
                 snapshot: owner.snapshotId,
                 project: owner.project.id,
-                symbol: symbol.id,
+                symbol: symbol.reference,
             });
         });
     }
@@ -4158,30 +4217,46 @@ export class NodeHandle {
      * is remembered so callers don't have to pass it explicitly.
      */
     canonicalProject;
+    /** The owning source file of a file-owned symbol's declaration. */
+    fileOwner;
     index;
     kind;
     path;
-    constructor(handle, canonicalProject) {
+    constructor(handle, canonicalProject, fileOwner) {
         const parsed = parseNodeHandle(handle);
         this.index = parsed.index;
         this.kind = parsed.kind;
         this.path = parsed.path;
         this.canonicalProject = canonicalProject;
+        this.fileOwner = fileOwner;
     }
     /**
      * 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.
+     * the handle is used. Declarations of file-owned symbols identify an exact source file and
+     * resolve through it, independently of any project.
      */
     get resolve() {
         const owner = this;
         return cacheGeneratorMethod(owner, "resolve", function (project = owner.canonicalProject) {
+            if (owner.fileOwner) {
+                const sourceFile = owner.fileOwner.record.file ?? owner.fetchOwnerFile(owner.fileOwner);
+                return sourceFile.getOrCreateNodeAtIndex(owner.index);
+            }
+            if (!project)
+                throw new Error(`Node handle for '${owner.path}' has no project context`);
             const sourceFile = project.program.getSourceFile(owner.path);
             if (!sourceFile) {
                 return undefined;
             }
             return sourceFile.getOrCreateNodeAtIndex(owner.index);
         }, function* (project = owner.canonicalProject) {
+            if (owner.fileOwner) {
+                const sourceFile = owner.fileOwner.record.file ?? (yield* owner.fetchOwnerFile.gen(owner.fileOwner));
+                return sourceFile.getOrCreateNodeAtIndex(owner.index);
+            }
+            if (!project)
+                throw new Error(`Node handle for '${owner.path}' has no project context`);
             const sourceFile = yield* project.program.getSourceFile.gen(owner.path);
             if (!sourceFile) {
                 return undefined;
@@ -4189,42 +4264,56 @@ export class NodeHandle {
             return sourceFile.getOrCreateNodeAtIndex(owner.index);
         });
     }
+    get fetchOwnerFile() {
+        const owner = this;
+        return cacheGeneratorMethod(owner, "fetchOwnerFile", function (fileOwner) {
+            const data = fileOwner.client.apiRequestBinary("getCachedSourceFile", { file: fileOwner.record.descriptor });
+            if (!data)
+                throw new Error(`Source file '${fileOwner.record.descriptor.fileName}' is not available`);
+            return fileOwner.cache.attachFile(fileOwner.record, new RemoteSourceFile(data, new Wtf8Decoder(), fileOwner.client.getTimingCollector()));
+        }, function* (fileOwner) {
+            const data = sourceFileResponseToUint8Array(yield* apiRequest("getCachedSourceFile", { file: fileOwner.record.descriptor }));
+            if (!data)
+                throw new Error(`Source file '${fileOwner.record.descriptor.fileName}' is not available`);
+            return fileOwner.cache.attachFile(fileOwner.record, new RemoteSourceFile(data, new Wtf8Decoder(), fileOwner.client.getTimingCollector()));
+        });
+    }
 }
 export class Symbol {
-    objectRegistry;
-    /**
-     * The project this symbol was first observed in, used as the default project for
-     * lookups that need a project context (members/exports/parent). Symbols are shared
-     * snapshot-wide, so these lookups can otherwise be ambiguous about which project to use.
-     */
-    canonicalProject;
-    id;
+    storage;
+    get id() {
+        return this.reference.id;
+    }
     /** The escaped (`__String`) name, used as the key in member/export tables. */
     escapedName;
     /** The display name (escaped underscores removed). */
     name;
     flags;
     checkFlags;
+    /** @internal */
+    reference;
     declarations;
     valueDeclaration;
     parent;
     exportSymbol;
     membersCache;
     exportsCache;
-    constructor(data, objectRegistry) {
-        this.objectRegistry = objectRegistry;
-        this.id = data.id;
+    constructor(data, storage) {
+        if (data.reference.kind !== storage.kind)
+            throw new Error(`Symbol ${data.reference.id} has mismatched ownership and storage`);
+        this.storage = storage;
+        this.reference = data.reference;
         this.escapedName = data.name;
         this.name = unescapeLeadingUnderscores(data.name);
         this.flags = data.flags;
         this.checkFlags = data.checkFlags;
-        const canonicalProject = objectRegistry.getProject(data.project);
-        if (!canonicalProject) {
-            throw new Error(`Symbol ${data.id} references unknown canonical project '${data.project}'`);
-        }
-        this.canonicalProject = canonicalProject;
-        this.declarations = (data.declarations ?? []).map(d => new NodeHandle(d, canonicalProject));
-        this.valueDeclaration = data.valueDeclaration ? new NodeHandle(data.valueDeclaration, canonicalProject) : undefined;
+        // 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;
         if (data.parent !== undefined)
             this.parent = data.parent;
         if (data.exportSymbol !== undefined)
@@ -4233,9 +4322,13 @@ export class Symbol {
     get getParent() {
         const owner = this;
         return cacheGeneratorMethod(owner, "getParent", function () {
-            return owner.objectRegistry.fetchSymbol(owner, "getParentOfSymbol", owner.parent, owner.canonicalProject.id);
+            if (!owner.parent)
+                return undefined;
+            return owner.fetchSymbol("getParentOfSymbol", owner.parent);
         }, function* () {
-            return yield* owner.objectRegistry.fetchSymbol.gen(owner, "getParentOfSymbol", owner.parent, owner.canonicalProject.id);
+            if (!owner.parent)
+                return undefined;
+            return yield* owner.fetchSymbol.gen("getParentOfSymbol", owner.parent);
         });
     }
     /**
@@ -4265,14 +4358,14 @@ export class Symbol {
     get fetchSymbolTable() {
         const owner = this;
         return cacheGeneratorMethod(owner, "fetchSymbolTable", function (method) {
-            const symbols = owner.objectRegistry.fetchSymbols(owner, method, undefined, owner.canonicalProject.id);
+            const symbols = owner.fetchSymbols(method);
             const table = new Map();
             for (const symbol of symbols) {
                 table.set(symbol.escapedName, symbol);
             }
             return table;
         }, function* (method) {
-            const symbols = yield* owner.objectRegistry.fetchSymbols.gen(owner, method, undefined, owner.canonicalProject.id);
+            const symbols = yield* owner.fetchSymbols.gen(method);
             const table = new Map();
             for (const symbol of symbols) {
                 table.set(symbol.escapedName, symbol);
@@ -4285,11 +4378,11 @@ export class Symbol {
         return cacheGeneratorMethod(owner, "getExportSymbol", function () {
             if (!owner.exportSymbol)
                 return owner;
-            return owner.objectRegistry.fetchSymbol(owner, "getExportSymbolOfSymbol", owner.exportSymbol, owner.canonicalProject.id);
+            return owner.fetchSymbol("getExportSymbolOfSymbol", owner.exportSymbol);
         }, function* () {
             if (!owner.exportSymbol)
                 return owner;
-            return yield* owner.objectRegistry.fetchSymbol.gen(owner, "getExportSymbolOfSymbol", owner.exportSymbol, owner.canonicalProject.id);
+            return yield* owner.fetchSymbol.gen("getExportSymbolOfSymbol", owner.exportSymbol);
         });
     }
     get getJsDocTags() {
@@ -4308,6 +4401,61 @@ export class Symbol {
             return yield* checker.getDocumentationCommentOfSymbol.gen(owner);
         });
     }
+    get fetchSymbol() {
+        const owner = this;
+        return cacheGeneratorMethod(owner, "fetchSymbol", function (method, reference) {
+            if (owner.storage.kind === SymbolOwnerKind.Snapshot) {
+                return owner.storage.registry.fetchSymbol(owner, method, reference);
+            }
+            const fileOwner = owner.storage.owner;
+            // A file-owned symbol's relationships are always owned by the same file.
+            const cached = reference.file === fileOwner.record.descriptor.nodeId ? fileOwner.record.symbols.get(reference.id) : undefined;
+            if (cached)
+                return cached;
+            const data = fileOwner.client.apiRequest(method, { symbol: owner.reference });
+            if (!data)
+                throw new Error(`${method} returned null symbol for Symbol ${owner.id}`);
+            return owner.internFileSymbol(fileOwner, data);
+        }, function* (method, reference) {
+            if (owner.storage.kind === SymbolOwnerKind.Snapshot) {
+                return yield* owner.storage.registry.fetchSymbol.gen(owner, method, reference);
+            }
+            const fileOwner = owner.storage.owner;
+            // A file-owned symbol's relationships are always owned by the same file.
+            const cached = reference.file === fileOwner.record.descriptor.nodeId ? fileOwner.record.symbols.get(reference.id) : undefined;
+            if (cached)
+                return cached;
+            const data = yield* apiRequest(method, { symbol: owner.reference });
+            if (!data)
+                throw new Error(`${method} returned null symbol for Symbol ${owner.id}`);
+            return owner.internFileSymbol(fileOwner, data);
+        });
+    }
+    get fetchSymbols() {
+        const owner = this;
+        return cacheGeneratorMethod(owner, "fetchSymbols", function (method) {
+            if (owner.storage.kind === SymbolOwnerKind.Snapshot) {
+                return owner.storage.registry.fetchSymbols(owner, method);
+            }
+            const fileOwner = owner.storage.owner;
+            const data = fileOwner.client.apiRequest(method, { symbol: owner.reference });
+            return data?.map(symbol => owner.internFileSymbol(fileOwner, symbol)) ?? [];
+        }, function* (method) {
+            if (owner.storage.kind === SymbolOwnerKind.Snapshot) {
+                return yield* owner.storage.registry.fetchSymbols.gen(owner, method);
+            }
+            const fileOwner = owner.storage.owner;
+            const data = yield* apiRequest(method, { symbol: owner.reference });
+            return data?.map(symbol => owner.internFileSymbol(fileOwner, symbol)) ?? [];
+        });
+    }
+    internFileSymbol(fileOwner, data) {
+        validateSymbolResponse(data);
+        const reference = data.reference;
+        if (reference.kind !== SymbolOwnerKind.File)
+            throw new Error(`Symbol ${reference.id} is not file-owned`);
+        return fileOwner.cache.getOrCreateSymbol(fileOwner.record, reference.file, reference.id, () => new Symbol(data, { kind: SymbolOwnerKind.File, owner: fileOwner }));
+    }
 }
 class TypeObject {
     objectRegistry;