carrick 0.3.97 → 0.3.99

package/sidecar/dist/src/index.js

@@ -11,6 +11,7 @@
  * - stderr is for logging
  * - Process stays alive between requests (warm standby)
  */
+import * as path from 'node:path';
 import * as readline from 'node:readline';
 import { parseRequest } from './validators.js';
 import { ProjectLoader } from './project-loader.js';
@@ -20,29 +21,36 @@ import { MonorepoBuilder } from './monorepo-builder.js';
 import { DefinitionResolver } from './definition-resolver.js';
 import { captureStub, findDisqualifyingTopTypes, jsonWireDeclarations, runCheck, } from './capture/index.js';
 import { Retyper } from './retype.js';
+import { ClientSemanticsVerifier } from './client-semantics.js';
 // ===========================================================================
 // Module-level state
 // ===========================================================================
 let projectLoader = null;
 let monorepoBuilder = null;
 let initTimeMs = null;
-let components = null;
+/**
+ * Components by project key (`ProjectLoader.projectKeyFor`): `''` is the
+ * default project, any other key the program of a project that owns some of
+ * the service's files (carrick#1604).
+ */
+let components = new Map();
 /**
  * Get the project-backed components, building the project if this is the
  * first request that needs it.
  *
  * @throws if init has not run, or if the project cannot be built
  */
-function projectComponents() {
+function projectComponents(key = '') {
     if (!projectLoader?.isInitialized()) {
         throw new Error('Sidecar not initialized. Call init first.');
     }
-    if (!components) {
+    let built = components.get(key);
+    if (!built) {
         // Bound here rather than read from the module slot inside the components:
         // a re-init drops `components` and points the slot at another service, and
         // nothing built over this project may follow it there.
         const loader = projectLoader;
-        const project = loader.getProject();
+        const project = loader.getProjectFor(key);
         const repoRoot = loader.getRepoRoot();
         // The module graph, where the project resolved through one, is the only
         // thing that can name the package a file belongs to: a Deno service
@@ -52,7 +60,7 @@ function projectComponents() {
             repoRoot,
             packageOf: (filePath) => loader.packageOf(filePath),
         });
-        components = {
+        built = {
             typeBundler: new TypeBundler({ project, repoRoot }),
             surfaceEmitter: new SurfaceEmitter({ project, repoRoot }),
             typeInferrer,
@@ -66,9 +74,43 @@ function projectComponents() {
             // (`npm/carrick/package.json`) resolves `typescript ^5.8.0` unpinned,
             // so an install can pair ts-morph's copy with a newer 5.x.
             retyper: new Retyper(project, typeInferrer, jsonWireDeclarations, findDisqualifyingTopTypes),
+            semanticsVerifier: new ClientSemanticsVerifier(project),
         };
+        components.set(key, built);
+    }
+    return built;
+}
+/** One bundle answer from the answers of several programs. */
+function mergeBundles(results) {
+    const symbol_failures = results.flatMap((r) => r.symbol_failures ?? []);
+    const answered = results.filter((r) => r.success);
+    if (answered.length === 0) {
+        return {
+            success: false,
+            symbol_failures,
+            errors: [...new Set(results.flatMap((r) => r.errors ?? []))],
+        };
+    }
+    return {
+        success: true,
+        dts_content: answered.map((r) => r.dts_content ?? '').join('\n'),
+        manifest: answered.flatMap((r) => r.manifest ?? []),
+        symbol_failures: symbol_failures.length > 0 ? symbol_failures : undefined,
+    };
+}
+/**
+ * Split a request's items by the project that types their file, keeping each
+ * group in request order. One group, the default project's, for a service
+ * whose tsconfig references nothing.
+ */
+function byProject(items, fileOf) {
+    // An empty request is still answered by the default project, as before.
+    const groups = new Map(items.length === 0 ? [['', []]] : []);
+    for (const item of items) {
+        const key = projectLoader?.projectKeyFor(fileOf(item)) ?? '';
+        groups.set(key, [...(groups.get(key) ?? []), item]);
     }
-    return components;
+    return groups;
 }
 // ===========================================================================
 // Request Handlers
@@ -82,7 +124,7 @@ function handleInit(request) {
         log(`Initializing with repo_root: ${request.repo_root}`);
         // Re-init re-scopes the sidecar to another root: drop everything built
         // over the previous project before resolving the new one.
-        components = null;
+        components = new Map();
         projectLoader = new ProjectLoader({
             repoRoot: request.repo_root,
             tsconfigPath: request.tsconfig_path,
@@ -128,7 +170,10 @@ function handleInit(request) {
 function handleBundle(request) {
     try {
         log(`Bundling ${request.symbols.length} symbol(s)`);
-        const result = projectComponents().typeBundler.bundle(request.symbols);
+        // A symbol named by a path is bundled from the program of the project
+        // that owns that file (carrick#1604).
+        const results = [...byProject(request.symbols, (symbol) => symbol.source_file)].map(([key, symbols]) => projectComponents(key).typeBundler.bundle(symbols));
+        const result = results.length === 1 ? results[0] : mergeBundles(results);
         if (!result.success) {
             return {
                 request_id: request.request_id,
@@ -274,7 +319,18 @@ async function handleCheckV2Async(request) {
 function handleInfer(request) {
     try {
         log(`Inferring ${request.requests.length} type(s)`);
-        const result = projectComponents().typeInferrer.infer(request.requests, request.extraction_config);
+        const results = [...byProject(request.requests, (item) => item.file_path)].map(([key, items]) => projectComponents(key).typeInferrer.infer(items, request.extraction_config));
+        const result = results.length === 1
+            ? results[0]
+            : (() => {
+                const inferred_types = results.flatMap((r) => r.inferred_types ?? []);
+                const errors = results.flatMap((r) => r.errors ?? []);
+                return {
+                    success: errors.length === 0 || inferred_types.length > 0,
+                    inferred_types,
+                    errors: errors.length > 0 ? errors : undefined,
+                };
+            })();
         return {
             request_id: request.request_id,
             status: result.success ? 'success' : 'error',
@@ -304,7 +360,19 @@ const RETYPE_BUDGET_MS = 600_000;
 function handleRetypeCheck(request) {
     try {
         log(`Retyping ${request.items.length} consumer call(s)`);
-        const outcomes = projectComponents().retyper.run(request.items, request.budget_ms ?? RETYPE_BUDGET_MS);
+        const budget = request.budget_ms ?? RETYPE_BUDGET_MS;
+        const groups = byProject(request.items.map((item, index) => ({ item, index })), ({ item }) => item.file_path);
+        const deadline = performance.now() + budget;
+        const outcomes = new Array(request.items.length);
+        for (const [key, entries] of groups) {
+            // One budget for the request, whichever programs it spans.
+            const remaining = groups.size === 1 ? budget : Math.max(0, deadline - performance.now());
+            projectComponents(key)
+                .retyper.run(entries.map(({ item }) => item), remaining)
+                .forEach((outcome, position) => {
+                outcomes[entries[position].index] = outcome;
+            });
+        }
         return { request_id: request.request_id, status: 'success', outcomes };
     }
     catch (err) {
@@ -313,6 +381,36 @@ function handleRetypeCheck(request) {
         return { request_id: request.request_id, status: 'error', errors: [error] };
     }
 }
+/**
+ * How long one verify_client_semantics request may spend before the checks it
+ * has not reached come back `unchecked` with reason `budget`. The first request
+ * on a service may pay the program build, which counts against it; the checks
+ * themselves are cheap. Well inside the scanner's 900s read deadline.
+ */
+const SEMANTICS_BUDGET_MS = 600_000;
+/**
+ * Handle the 'verify_client_semantics' action - check library-semantics
+ * claims against each package's type declarations (carrick#1564)
+ */
+function handleVerifyClientSemantics(request) {
+    try {
+        const { semanticsVerifier } = projectComponents();
+        const fromDir = path.resolve(projectLoader.getRepoRoot(), request.from_dir);
+        log(`Verifying ${request.checks.length} client-semantics claim(s) from ${fromDir}`);
+        const { semantics, modules } = semanticsVerifier.run(fromDir, request.checks, request.budget_ms ?? SEMANTICS_BUDGET_MS);
+        return {
+            request_id: request.request_id,
+            status: 'success',
+            semantics,
+            semantics_modules: modules,
+        };
+    }
+    catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        logError(`Client-semantics check failed: ${error}`);
+        return { request_id: request.request_id, status: 'error', errors: [error] };
+    }
+}
 /**
  * Handle the 'build_workspace' action - build synthetic monorepo workspace
  */
@@ -463,6 +561,8 @@ function handleRequest(request) {
             return handleResolveDefinitions(request);
         case 'retype_check':
             return handleRetypeCheck(request);
+        case 'verify_client_semantics':
+            return handleVerifyClientSemantics(request);
         case 'health':
             return handleHealth(request);
         case 'shutdown':

package/sidecar/dist/src/module-format.d.ts

@@ -0,0 +1,32 @@
+/**
+ * How the init'd project resolves an import: in the mode the compiler picks
+ * for the file that imports it (carrick#1619).
+ *
+ * Under `module` `node16`..`nodenext` the compiler reads each file's own
+ * format (its nearest `package.json` `"type"`, or its extension) to decide
+ * whether an import resolves with the `import` or the `require` export
+ * conditions. The program asks its host to create each file with that format,
+ * but ts-morph's host creates every file with the script target only, so no
+ * file had a format and every import resolved as a `require`. A package whose
+ * `exports` entry only has an `import` branch did not resolve at all, while
+ * the capture, which uses the compiler directly, resolved the same import.
+ *
+ * This resolution host gives the importing file its format before its imports
+ * are resolved, then resolves each import as the compiler's default does:
+ * `ts.resolveModuleName` in the mode `ts.getModeForUsageLocation` reads off
+ * that import. The format is only set under `node16`..`nodenext`. Under other
+ * `module` settings the compiler still takes an import's mode from its syntax
+ * (`import`, `require`, a `resolution-mode` attribute) and reads a file's
+ * format only in narrow cases; setting it there made answers worse, because
+ * ts-morph's TypeScript copy shares one resolution-cache entry across modes
+ * under Bundler (carrick#1632), so those settings keep their old modes.
+ *
+ * The hook receives one entry per import, by module name, so one name
+ * imported twice in different modes (a `require` beside an `import`) needs
+ * each entry matched to its own import. It is, by position, when every import
+ * of the name is being resolved; when only some of them are (the compiler
+ * reusing earlier answers) and their modes differ, the entry cannot be placed
+ * and is left unresolved rather than given another import's mode.
+ */
+import { type ResolutionHostFactory } from 'ts-morph';
+export declare const moduleFormatResolutionHost: ResolutionHostFactory;

package/sidecar/dist/src/module-format.js

@@ -0,0 +1,102 @@
+/**
+ * How the init'd project resolves an import: in the mode the compiler picks
+ * for the file that imports it (carrick#1619).
+ *
+ * Under `module` `node16`..`nodenext` the compiler reads each file's own
+ * format (its nearest `package.json` `"type"`, or its extension) to decide
+ * whether an import resolves with the `import` or the `require` export
+ * conditions. The program asks its host to create each file with that format,
+ * but ts-morph's host creates every file with the script target only, so no
+ * file had a format and every import resolved as a `require`. A package whose
+ * `exports` entry only has an `import` branch did not resolve at all, while
+ * the capture, which uses the compiler directly, resolved the same import.
+ *
+ * This resolution host gives the importing file its format before its imports
+ * are resolved, then resolves each import as the compiler's default does:
+ * `ts.resolveModuleName` in the mode `ts.getModeForUsageLocation` reads off
+ * that import. The format is only set under `node16`..`nodenext`. Under other
+ * `module` settings the compiler still takes an import's mode from its syntax
+ * (`import`, `require`, a `resolution-mode` attribute) and reads a file's
+ * format only in narrow cases; setting it there made answers worse, because
+ * ts-morph's TypeScript copy shares one resolution-cache entry across modes
+ * under Bundler (carrick#1632), so those settings keep their old modes.
+ *
+ * The hook receives one entry per import, by module name, so one name
+ * imported twice in different modes (a `require` beside an `import`) needs
+ * each entry matched to its own import. It is, by position, when every import
+ * of the name is being resolved; when only some of them are (the compiler
+ * reusing earlier answers) and their modes differ, the entry cannot be placed
+ * and is left unresolved rather than given another import's mode.
+ */
+import { ts } from 'ts-morph';
+/** Whether the compiler decides an import's mode from the importing file's format. */
+function formatDecidesMode(options) {
+    const kind = options.module;
+    return kind !== undefined && kind >= ts.ModuleKind.Node16 && kind <= ts.ModuleKind.NodeNext;
+}
+/**
+ * The literals in `file` the program resolves, by module name and in source
+ * order: its imports, then its module augmentations. Neither list is in the
+ * public declaration file.
+ */
+function usagesOf(file) {
+    const internal = file;
+    const usages = new Map();
+    const add = (literal) => {
+        usages.set(literal.text, [...(usages.get(literal.text) ?? []), literal]);
+    };
+    for (const literal of internal.imports ?? [])
+        add(literal);
+    for (const literal of internal.moduleAugmentations ?? []) {
+        if (ts.isStringLiteral(literal))
+            add(literal);
+    }
+    return usages;
+}
+/** Why a module name cannot be given one mode: see the header. */
+const UNPLACED = Symbol('unplaced');
+export const moduleFormatResolutionHost = (host, getOptions) => {
+    let cache;
+    let cacheOptions;
+    const cacheFor = (options) => {
+        if (!cache || cacheOptions !== options) {
+            cache = ts.createModuleResolutionCache(process.cwd(), (fileName) => fileName, options);
+            cacheOptions = options;
+        }
+        return cache;
+    };
+    return {
+        resolveModuleNames: (moduleNames, containingFile, _reusedNames, redirectedReference, options, containingSourceFile) => {
+            const compilerOptions = options ?? getOptions();
+            const resolutionCache = cacheFor(compilerOptions);
+            if (containingSourceFile &&
+                containingSourceFile.impliedNodeFormat === undefined &&
+                formatDecidesMode(compilerOptions)) {
+                containingSourceFile.impliedNodeFormat =
+                    ts.getImpliedNodeFormatForFile(containingFile, resolutionCache.getPackageJsonInfoCache(), host, compilerOptions);
+            }
+            const usages = containingSourceFile ? usagesOf(containingSourceFile) : undefined;
+            const asked = new Map();
+            for (const name of moduleNames)
+                asked.set(name, (asked.get(name) ?? 0) + 1);
+            const seen = new Map();
+            const modeOf = (name) => {
+                const occurrence = seen.get(name) ?? 0;
+                seen.set(name, occurrence + 1);
+                const literals = usages?.get(name) ?? [];
+                if (!containingSourceFile || literals.length === 0)
+                    return undefined;
+                const modes = literals.map((literal) => ts.getModeForUsageLocation(containingSourceFile, literal, compilerOptions));
+                if (new Set(modes).size === 1)
+                    return modes[0];
+                return asked.get(name) === literals.length ? modes[occurrence] : UNPLACED;
+            };
+            return moduleNames.map((name) => {
+                const mode = modeOf(name);
+                if (mode === UNPLACED)
+                    return undefined;
+                return ts.resolveModuleName(name, containingFile, compilerOptions, host, resolutionCache, redirectedReference, mode).resolvedModule;
+            });
+        },
+    };
+};

package/sidecar/dist/src/project-loader.d.ts

@@ -61,6 +61,12 @@ export declare class ProjectLoader {
      * build, so it is there from the first `getProject()` onwards.
      */
     private denoProject;
+    /** The tsconfig the service names, when the project is built from one. */
+    private namedTsconfigPath;
+    /** Each file's owning config (carrick#1604), resolved on first use. */
+    private configPathFor;
+    /** Programs built for owning projects other than the named tsconfig. */
+    private readonly ownerProjects;
     private readonly repoRoot;
     private readonly tsconfigPath;
     private readonly tsconfigSnapshot;
@@ -82,6 +88,24 @@ export declare class ProjectLoader {
      * Convert a TsconfigSnapshot to ts-morph CompilerOptions
      */
     private snapshotToCompilerOptions;
+    /** A ts-morph project built from one tsconfig and the files it lists. */
+    private projectFromConfig;
+    /**
+     * Which project types `file` (carrick#1604): the key of its owning
+     * project's program, or `''` for the default one. A tsconfig that
+     * references other projects owns only the files it lists itself; any other
+     * file belongs to the first project it references (depth-first, in
+     * declared order) whose file list includes it, and is typed under that
+     * project's options. A file no project includes, and every request that
+     * names no file, uses the default project, built from the named tsconfig
+     * as before.
+     */
+    projectKeyFor(file?: string): string;
+    /**
+     * The project behind a key from `projectKeyFor`, built on first use and
+     * kept: a service whose files all belong to one project builds one.
+     */
+    getProjectFor(key: string): Project;
     /**
      * Get the ts-morph Project, building it on first call.
      *

package/sidecar/dist/src/project-loader.js

@@ -12,7 +12,8 @@
 import { Project } from 'ts-morph';
 import * as path from 'node:path';
 import * as fs from 'node:fs';
-import { DenoProject, findDenoConfig } from './capture/index.js';
+import { DenoProject, findDenoConfig, serviceConfigPath } from './capture/index.js';
+import { moduleFormatResolutionHost } from './module-format.js';
 /**
  * Source-file patterns used when the repo declares no tsconfig, relative to
  * the repo root. `node_modules` is excluded explicitly: a glob that matches
@@ -115,6 +116,12 @@ export class ProjectLoader {
      * build, so it is there from the first `getProject()` onwards.
      */
     denoProject;
+    /** The tsconfig the service names, when the project is built from one. */
+    namedTsconfigPath;
+    /** Each file's owning config (carrick#1604), resolved on first use. */
+    configPathFor;
+    /** Programs built for owning projects other than the named tsconfig. */
+    ownerProjects = new Map();
     repoRoot;
     tsconfigPath;
     tsconfigSnapshot;
@@ -200,10 +207,8 @@ export class ProjectLoader {
                 }
                 else if (tsconfigPath) {
                     this.log(`Project will load with tsconfig: ${tsconfigPath}`);
-                    this.buildProject = () => new Project({
-                        tsConfigFilePath: tsconfigPath,
-                        skipAddingFilesFromTsConfig: false,
-                    });
+                    this.namedTsconfigPath = tsconfigPath;
+                    this.buildProject = () => this.projectFromConfig(tsconfigPath);
                 }
                 else {
                     this.log('No tsconfig.json found, using default compiler options');
@@ -306,6 +311,49 @@ export class ProjectLoader {
         }
         return result;
     }
+    /** A ts-morph project built from one tsconfig and the files it lists. */
+    projectFromConfig(configPath) {
+        return new Project({
+            tsConfigFilePath: configPath,
+            skipAddingFilesFromTsConfig: false,
+            // Each import resolves in its file's own module format (carrick#1619).
+            resolutionHost: moduleFormatResolutionHost,
+        });
+    }
+    /**
+     * Which project types `file` (carrick#1604): the key of its owning
+     * project's program, or `''` for the default one. A tsconfig that
+     * references other projects owns only the files it lists itself; any other
+     * file belongs to the first project it references (depth-first, in
+     * declared order) whose file list includes it, and is typed under that
+     * project's options. A file no project includes, and every request that
+     * names no file, uses the default project, built from the named tsconfig
+     * as before.
+     */
+    projectKeyFor(file) {
+        if (!this.namedTsconfigPath || file === undefined)
+            return '';
+        this.configPathFor ??= serviceConfigPath(this.namedTsconfigPath, (d) => this.logError(d));
+        const config = this.configPathFor(path.resolve(this.repoRoot, file));
+        return config === this.namedTsconfigPath ? '' : config;
+    }
+    /**
+     * The project behind a key from `projectKeyFor`, built on first use and
+     * kept: a service whose files all belong to one project builds one.
+     */
+    getProjectFor(key) {
+        if (key === '')
+            return this.getProject();
+        let project = this.ownerProjects.get(key);
+        if (!project) {
+            const startTime = performance.now();
+            project = this.projectFromConfig(key);
+            this.ownerProjects.set(key, project);
+            this.log(`Project for ${key}, the project that owns the requested files, built in ` +
+                `${Math.round(performance.now() - startTime)}ms (${project.getSourceFiles().length} source files)`);
+        }
+        return project;
+    }
     /**
      * Get the ts-morph Project, building it on first call.
      *

package/sidecar/dist/src/types.d.ts

@@ -320,10 +320,64 @@ export interface RetypeCheckRequest extends BaseRequest {
     /** Time the request may spend; items it does not reach abstain. */
     budget_ms?: number;
 }
+/**
+ * One library-semantics claim to check against the package's own type
+ * declarations, on one receiver (carrick#1564). The unit of verification is
+ * the pair `(claim_id, receiver)`.
+ */
+export interface SemanticsCheck {
+    claim_id: string;
+    /** Module specifier, resolved from the request's `from_dir`. */
+    package: string;
+    /** `"default"` or a named export. */
+    export: string;
+    /** `"export"` or `"instance:<factory member>"`. */
+    receiver: string;
+    claim: {
+        kind: 'factory';
+        member: string;
+        base_url_key: string;
+    } | {
+        kind: 'verb';
+        member: string;
+        method: string;
+    } | {
+        kind: 'verb_body';
+        member: string;
+        args: 'path_body' | 'path_options';
+        body_key?: string;
+    } | {
+        kind: 'request';
+        member: string | null;
+        args: 'config' | 'path_options';
+        url_key?: string;
+        method_key: string;
+    } | {
+        kind: 'request_body';
+        member: string | null;
+        args: 'config' | 'path_options';
+        url_key?: string;
+        method_key: string;
+        body_key: string;
+    };
+}
+/**
+ * Check library-semantics claims against each package's type declarations.
+ * Needs `init`: module resolution runs under the service's compiler options,
+ * in the service's program.
+ */
+export interface VerifyClientSemanticsRequest extends BaseRequest {
+    action: 'verify_client_semantics';
+    /** Absolute service root; module resolution starts here. */
+    from_dir: string;
+    checks: SemanticsCheck[];
+    /** Checks not reached in time come back `unchecked` with reason `budget`. */
+    budget_ms?: number;
+}
 /**
  * Union type for all possible sidecar requests
  */
-export type SidecarRequest = RetypeCheckRequest | InitRequest | BundleRequest | EmitSurfaceRequest | CaptureV2Request | CheckV2Request | InferRequest | BuildWorkspaceRequest | CheckCompatibilityRequest | ResolveDefinitionsRequest | HealthRequest | ShutdownRequest;
+export type SidecarRequest = RetypeCheckRequest | VerifyClientSemanticsRequest | InitRequest | BundleRequest | EmitSurfaceRequest | CaptureV2Request | CheckV2Request | InferRequest | BuildWorkspaceRequest | CheckCompatibilityRequest | ResolveDefinitionsRequest | HealthRequest | ShutdownRequest;
 /**
  * Request for a specific symbol to be bundled
  */
@@ -532,10 +586,37 @@ export interface RetypeCheckResponse extends BaseResponse {
     outcomes?: RetypeOutcome[];
     errors?: string[];
 }
+/**
+ * The verdict on one `(claim_id, receiver)` pair.
+ *
+ * - `verified`: the declarations satisfy the claim.
+ * - `failed`: the declarations resolved and contradict it.
+ * - `unchecked`: the declarations could not be read.
+ */
+export interface SemanticsResult {
+    claim_id: string;
+    receiver: string;
+    verdict: 'verified' | 'failed' | 'unchecked';
+    /** Absent exactly when verified. */
+    reason?: string;
+}
+/** How one package of the request resolved, for logs. */
+export interface SemanticsModule {
+    package: string;
+    resolved_file?: string;
+    installed_version?: string;
+    reason?: string;
+}
+export interface VerifyClientSemanticsResponse extends BaseResponse {
+    /** Exactly one per check, in request order. */
+    semantics?: SemanticsResult[];
+    semantics_modules?: SemanticsModule[];
+    errors?: string[];
+}
 /**
  * Union type for all possible sidecar responses
  */
-export type SidecarResponse = RetypeCheckResponse | InitResponse | BundleResponse | EmitSurfaceResponse | CaptureV2Response | CheckV2Response | InferResponse | BuildWorkspaceResponse | CheckCompatibilityResponse | ResolveDefinitionsResponse | HealthResponse | ShutdownResponse | ErrorResponse;
+export type SidecarResponse = RetypeCheckResponse | VerifyClientSemanticsResponse | InitResponse | BundleResponse | EmitSurfaceResponse | CaptureV2Response | CheckV2Response | InferResponse | BuildWorkspaceResponse | CheckCompatibilityResponse | ResolveDefinitionsResponse | HealthResponse | ShutdownResponse | ErrorResponse;
 /**
  * An entry in the type manifest
  */
@@ -604,8 +685,9 @@ export interface InferredType {
      * anchor symbol has a resolvable source declaration. Lets the scanner's
      * pub/sub two-anchor arbitration (carrick#413) re-aim a demoted explicit
      * `SymbolRequest` at the tsc-witnessed payload type: the bundler requires
-     * the symbol to be DECLARED in the request's `source_file`, and the
-     * inference is the only party that knows where that is. Reported only by
+     * the symbol to be declared in, or re-exported by, the request's
+     * `source_file`, and the inference is the only party that knows where that
+     * is. Reported only by
      * the pub/sub infer kinds (`function_param`, `expression`); other kinds
      * omit it.
      */