gitnexus 1.6.11-rc.21 → 1.6.11-rc.22

package/dist/core/group/cross-impact.d.ts

@@ -62,6 +62,9 @@ export declare function validateGroupImpactParams(params: Record<string, unknown
     name: string;
     repoPath: string;
     target: string;
+    target_uid?: string;
+    file_path?: string;
+    kind?: string;
     direction: 'upstream' | 'downstream';
     maxDepth: number;
     crossDepth: number;

package/dist/core/group/cross-impact.js

@@ -103,13 +103,21 @@ export function clampTimeout(timeoutMs) {
 export function validateGroupImpactParams(params) {
     const name = String(params.name ?? '').trim();
     const repoPath = String(params.repo ?? '').trim();
-    const target = String(params.target ?? '').trim();
+    // Optional string, same helper shape as cross-trace's `str()`: empty/blank
+    // counts as absent so `target_uid: ''` degrades to the name lookup rather
+    // than a zero-ambiguity lookup of the empty uid. Parsed before the required
+    // check so UID-only callers (MCP impact schema requires `direction`, not
+    // `target`) are accepted.
+    const str = (v) => typeof v === 'string' && v.trim() !== '' ? v : undefined;
+    const targetName = String(params.target ?? '').trim();
+    const target_uidEarly = str(params.target_uid);
     if (!name)
         return { ok: false, error: 'name is required' };
     if (!repoPath)
         return { ok: false, error: 'repo is required (group repo path, e.g. app/backend)' };
-    if (!target)
-        return { ok: false, error: 'target is required' };
+    if (!targetName && !target_uidEarly)
+        return { ok: false, error: 'target or target_uid is required' };
+    const target = targetName || target_uidEarly;
     if (params.service !== undefined &&
         params.service !== null &&
         String(params.service).trim() === '') {
@@ -133,6 +141,9 @@ export function validateGroupImpactParams(params) {
         minConfidence = 1;
     const service = normalizeServicePrefix(params.service);
     const subgroup = typeof params.subgroup === 'string' ? params.subgroup : undefined;
+    const target_uid = target_uidEarly;
+    const file_path = str(params.file_path);
+    const kind = str(params.kind);
     // Clamp at the validate boundary so the downstream `deadline` (line
     // ~366) and `safeLocalImpact`'s `setTimeout` both see a single
     // bounded value. Without this, the outer deadline budgeted Phase-2
@@ -150,6 +161,9 @@ export function validateGroupImpactParams(params) {
         name,
         repoPath,
         target,
+        target_uid,
+        file_path,
+        kind,
         direction,
         maxDepth,
         crossDepth,
@@ -448,7 +462,7 @@ export async function runGroupImpact(deps, params) {
     const parsed = validateGroupImpactParams(params);
     if (parsed.ok === false)
         return { error: parsed.error };
-    const { name, repoPath, target, direction, maxDepth, crossDepth: _crossDepth, crossDepthWarning, relationTypes, includeTests, minConfidence, service: servicePrefix, subgroup, timeoutMs, } = parsed;
+    const { name, repoPath, target, target_uid, file_path, kind, direction, maxDepth, crossDepth: _crossDepth, crossDepthWarning, relationTypes, includeTests, minConfidence, service: servicePrefix, subgroup, timeoutMs, } = parsed;
     const groupDir = getGroupDir(deps.gitnexusDir, name);
     let config;
     try {
@@ -464,6 +478,14 @@ export async function runGroupImpact(deps, params) {
         return { error: resolved.error };
     const impactParams = {
         target,
+        // Selector params pass through to the member repo's impact (the port
+        // contract in service.ts documents them), so the single-repo tool's
+        // "re-call with target_uid to disambiguate" loop works unchanged in
+        // group mode. `undefined` keeps the call shape flat — same convention
+        // as the relationTypes line below.
+        target_uid,
+        file_path,
+        kind,
         direction,
         maxDepth,
         relationTypes: relationTypes && relationTypes.length > 0 ? relationTypes : undefined,

package/dist/core/group/extractors/http-patterns/java.js

@@ -2,7 +2,7 @@ import Java from 'tree-sitter-java';
 import { compilePatterns, runCompiledPatterns, unquoteLiteral, } from '../tree-sitter-scanner.js';
 import { springAnnotationHttpMethods, intersectSpringHttpMethods, isRouteMemberKey, findEnclosingClass, joinPath, } from '../../../ingestion/route-extractors/spring-shared.js';
 import { REST_TEMPLATE_TO_HTTP, WEB_CLIENT_SHORT_TO_HTTP, WEB_CLIENT_LONG_VERB_RE, EXCHANGE_ANNOTATION_TO_HTTP, parseRequestLine, pushPrefix, scanSpringInheritanceProject, OPENFEIGN_FRAMEWORK, HTTP_INTERFACE_FRAMEWORK, FEIGN_CONFIDENCE, REQUEST_LINE_CONFIDENCE, EXCHANGE_CONFIDENCE, } from './spring-consumer-shared.js';
-import { extractJavaModuleConstants, foldJavaOperands, isJavaConstantFile, parseJavaConstOperands, } from '../../../ingestion/route-extractors/java-const-resolver.js';
+import { expandJavaWildcardStaticImports, extractJavaModuleConstants, foldJavaOperands, isJavaConstantFile, parseJavaConstOperands, prepareJavaRouteConstants, } from '../../../ingestion/route-extractors/java-const-resolver.js';
 import { extractStaticPathExpression, inferOkHttpMethod, inferHttpClientMethod, okHttpUrlRootsAtBuilder, httpClientUriRootsAtNewBuilder, httpClientChainHasUriCall, } from './java-static-path.js';
 /**
  * Java HTTP plugin. Handles:
@@ -789,7 +789,10 @@ export const JAVA_HTTP_PLUGIN = {
                 if (!tree)
                     continue;
                 const mc = extractJavaModuleConstants(tree);
-                if (mc.literals.size > 0 || mc.exprs.size > 0 || mc.imports.size > 0) {
+                if (mc.literals.size > 0 ||
+                    mc.exprs.size > 0 ||
+                    mc.imports.size > 0 ||
+                    (mc.wildcardImports?.length ?? 0) > 0) {
                     constants.set(rel, mc);
                 }
             }
@@ -800,7 +803,14 @@ export const JAVA_HTTP_PLUGIN = {
                 continue;
             }
         }
-        return { constants };
+        // On-demand static imports (`import static a.b.C.*`) were recorded as
+        // pending class FQNs during extraction; materialize their bare-name
+        // bindings now that the whole map exists. A wildcard's target is itself
+        // a constants file, so it is necessarily a map entry — anything else
+        // degrades to the fold's skip floor. In-place: each entry is owned by
+        // this map, and every file is expanded exactly once.
+        const constantIndex = prepareJavaRouteConstants(constants);
+        return { constants, constantIndex };
     },
     scan(tree, repoContext, fileRel) {
         const out = [];
@@ -832,8 +842,12 @@ export const JAVA_HTTP_PLUGIN = {
                 return foldConstants;
             try {
                 const mc = extractJavaModuleConstants(tree);
-                if (mc.imports.size > 0) {
+                // A file carrying ONLY wildcard static imports has an empty import
+                // table pre-expansion — overlay it too, then materialize the promised
+                // bindings against the repo map before it becomes a fold target.
+                if (mc.imports.size > 0 || (mc.wildcardImports?.length ?? 0) > 0) {
                     const merged = new Map(javaCtx.constants);
+                    expandJavaWildcardStaticImports(mc, fileRel, merged, javaCtx.constantIndex);
                     merged.set(fileRel, mc);
                     foldConstants = merged;
                 }

package/dist/core/group/extractors/http-patterns/kotlin.js

@@ -1260,6 +1260,7 @@ function buildKotlinPlugin(language) {
                     if (mc.literals.size > 0 ||
                         mc.exprs.size > 0 ||
                         mc.imports.size > 0 ||
+                        (mc.wildcardImports?.length ?? 0) > 0 ||
                         unfoldableDeclarationsOf(mc).size > 0) {
                         // POSIX key (see `normalizeRel`); `readFile` above got the raw `rel`.
                         constants.set(normalizeRel(rel), mc);
@@ -1303,6 +1304,7 @@ function buildKotlinPlugin(language) {
                     if (mc.literals.size > 0 ||
                         mc.exprs.size > 0 ||
                         mc.imports.size > 0 ||
+                        (mc.wildcardImports?.length ?? 0) > 0 ||
                         unfoldableDeclarationsOf(mc).size > 0) {
                         foldIndex = overlayKotlinConstantIndex(kotlinCtx.index, fileKey, mc);
                     }

package/dist/core/group/normalization.d.ts

@@ -1,3 +1,40 @@
-import type { CrossLink, StoredContract } from './types.js';
+import type { CrossLink, CrossLinkEndpoint, StoredContract } from './types.js';
+/**
+ * True when a link endpoint carries no resolved graph symbol — empty
+ * `symbolUid` or a missing/empty `symbolRef`.
+ *
+ * Sync marks a cross-link `degraded: true` when this holds for the PROVIDER
+ * endpoint (`to`): the contract boundary is proven, but the empty uid can
+ * never match a Phase-1 impact symbol id, so cross-repo fan-out across the
+ * link silently yields nothing (the classic case is a provider whose handler
+ * failed to resolve, leaving `symbolName` degraded to the file name with one
+ * pseudo-symbol carrying every route in that file). Consumer-side (`from`)
+ * emptiness is deliberately NOT degraded — several extractors (topics, grpc)
+ * legitimately emit consumer contracts without a per-call symbol, and the
+ * anchor that matters for far-side fan-out is the provider's.
+ *
+ * Kept next to the endpoint merge logic because `dedupeCrossLinks` must
+ * re-derive the flag after a merge: `mergeEndpoints` backfills `symbolUid`
+ * from the losing twin, which can invalidate a flag carried in from the winner.
+ *
+ * NOT unresolved: a deterministic `manifest::<repo>::<contractId>` synthetic
+ * uid (see `manifestSymbolUid`). Manifest endpoints fall back to it precisely
+ * when the graph has no symbol for them — its empty `symbolRef.filePath` would
+ * otherwise trip the check below — yet cross-impact anchors those links by
+ * design (#2722: the crossing is preserved with `fanout_status:
+ * 'not_attempted'` instead of silently yielding cross=0). The prefix is the
+ * canonical discriminator — real indexer uids never start with `manifest::`
+ * — and `cross-impact.ts` branches on the same test. Encoding the exemption
+ * HERE (not at the sync marking call site) keeps marking and the post-merge
+ * re-derivation from drifting apart, and keeps the flag's meaning exactly what
+ * `types.ts` documents: "distinct from manifest::… synthetic UIDs".
+ */
+export declare function isUnresolvedEndpoint(endpoint: CrossLinkEndpoint): boolean;
+/**
+ * Derive `degraded` from the provider endpoint. Present (`true`) only when
+ * unresolved; deleted otherwise so contracts.json stays "carried only when
+ * meaningful" (`'degraded' in link === false` for anchored links).
+ */
+export declare function applyDegradedFlag(link: CrossLink): CrossLink;
 export declare function dedupeContracts(items: StoredContract[]): StoredContract[];
 export declare function dedupeCrossLinks(items: CrossLink[]): CrossLink[];

package/dist/core/group/normalization.js

@@ -83,6 +83,59 @@ function crossLinkKey(link) {
         endpointKey(link.to),
     ].join('\0');
 }
+/**
+ * True when a link endpoint carries no resolved graph symbol — empty
+ * `symbolUid` or a missing/empty `symbolRef`.
+ *
+ * Sync marks a cross-link `degraded: true` when this holds for the PROVIDER
+ * endpoint (`to`): the contract boundary is proven, but the empty uid can
+ * never match a Phase-1 impact symbol id, so cross-repo fan-out across the
+ * link silently yields nothing (the classic case is a provider whose handler
+ * failed to resolve, leaving `symbolName` degraded to the file name with one
+ * pseudo-symbol carrying every route in that file). Consumer-side (`from`)
+ * emptiness is deliberately NOT degraded — several extractors (topics, grpc)
+ * legitimately emit consumer contracts without a per-call symbol, and the
+ * anchor that matters for far-side fan-out is the provider's.
+ *
+ * Kept next to the endpoint merge logic because `dedupeCrossLinks` must
+ * re-derive the flag after a merge: `mergeEndpoints` backfills `symbolUid`
+ * from the losing twin, which can invalidate a flag carried in from the winner.
+ *
+ * NOT unresolved: a deterministic `manifest::<repo>::<contractId>` synthetic
+ * uid (see `manifestSymbolUid`). Manifest endpoints fall back to it precisely
+ * when the graph has no symbol for them — its empty `symbolRef.filePath` would
+ * otherwise trip the check below — yet cross-impact anchors those links by
+ * design (#2722: the crossing is preserved with `fanout_status:
+ * 'not_attempted'` instead of silently yielding cross=0). The prefix is the
+ * canonical discriminator — real indexer uids never start with `manifest::`
+ * — and `cross-impact.ts` branches on the same test. Encoding the exemption
+ * HERE (not at the sync marking call site) keeps marking and the post-merge
+ * re-derivation from drifting apart, and keeps the flag's meaning exactly what
+ * `types.ts` documents: "distinct from manifest::… synthetic UIDs".
+ */
+export function isUnresolvedEndpoint(endpoint) {
+    if (endpoint.symbolUid.startsWith('manifest::'))
+        return false;
+    return (!endpoint.symbolUid ||
+        !endpoint.symbolRef ||
+        !endpoint.symbolRef.filePath ||
+        !endpoint.symbolRef.name);
+}
+/**
+ * Derive `degraded` from the provider endpoint. Present (`true`) only when
+ * unresolved; deleted otherwise so contracts.json stays "carried only when
+ * meaningful" (`'degraded' in link === false` for anchored links).
+ */
+export function applyDegradedFlag(link) {
+    const next = { ...link };
+    if (isUnresolvedEndpoint(next.to)) {
+        next.degraded = true;
+    }
+    else {
+        delete next.degraded;
+    }
+    return next;
+}
 export function dedupeContracts(items) {
     const deduped = new Map();
     for (const contract of items) {
@@ -104,12 +157,15 @@ export function dedupeCrossLinks(items) {
         const keepIncoming = link.confidence > existing.confidence;
         const primary = keepIncoming ? link : existing;
         const secondary = keepIncoming ? existing : link;
-        deduped.set(key, {
+        const merged = {
             ...primary,
             confidence: Math.max(existing.confidence, link.confidence),
             from: mergeEndpoints(primary.from, secondary.from),
             to: mergeEndpoints(primary.to, secondary.to),
-        });
+        };
+        // Re-derive after mergeEndpoints: a richer twin can backfill `to.symbolUid`
+        // and must not leave a stale `degraded` flag on an now-anchored link.
+        deduped.set(key, applyDegradedFlag(merged));
     }
-    return [...deduped.values()];
+    return [...deduped.values()].map(applyDegradedFlag);
 }

package/dist/core/group/service.d.ts

@@ -15,6 +15,17 @@ export interface GroupToolPort {
     resolveRepo(repoParam?: string): Promise<GroupRepoHandle>;
     impact(repo: GroupRepoHandle, params: {
         target: string;
+        /**
+         * Target-selector params, same semantics as the single-repo `impact`
+         * tool: `target_uid` is the zero-ambiguity lookup (it wins over the
+         * name), `file_path`/`kind` narrow a name shared by several symbols
+         * (e.g. same-named Api/Impl/Controller layers). The port implementation
+         * consumes them directly; the Phase-1 caller in cross-impact.ts is
+         * responsible for threading them from the MCP `impact` args.
+         */
+        target_uid?: string;
+        file_path?: string;
+        kind?: string;
         direction: 'upstream' | 'downstream';
         maxDepth?: number;
         relationTypes?: string[];

package/dist/core/group/service.js

@@ -341,6 +341,14 @@ export class GroupService {
             // can otherwise see contract counts that disagree with this payload, with
             // nothing here explaining why the write was skipped.
             registryOutcome: result.registryOutcome,
+            // Data-quality signals surfaced from the sync run: links whose provider
+            // endpoint never resolved to a graph symbol, per-repo extraction
+            // failures with reasons, and operator warnings (e.g. bridge.lbug write
+            // failed after contracts.json was written). Always present so MCP
+            // consumers can branch on them without existence checks.
+            degradedLinks: result.degradedLinks,
+            failedRepos: result.failedRepos,
+            warnings: result.warnings,
         };
     }
     async groupContracts(params) {

package/dist/core/group/sync.d.ts

@@ -47,6 +47,27 @@ export interface SyncResult {
      * none of that repo's contracts are in `contracts`.
      */
     unreadableRepos: string[];
+    /**
+     * Cross-links whose provider endpoint has no resolved graph symbol
+     * (`degraded: true` on the link — see `isUnresolvedEndpoint`). The boundary
+     * is proven but cross-impact fan-out cannot anchor it; the usual remedy is
+     * re-analyzing the provider repo so its handlers resolve.
+     */
+    degradedLinks: number;
+    /**
+     * Repos whose per-repo extraction threw (init, an extractor, or the
+     * snapshot read). Each still lands in `unreadableRepos` (group path) —
+     * unchanged downstream semantics — but carries its failure reason here: the
+     * catch used to swallow the exception, leaving contracts already pushed by
+     * earlier extractors in this iteration as silent half-repo data. `repo` is
+     * that same group path (e.g. `app/backend`), not the registry display name.
+     */
+    failedRepos: Array<{
+        repo: string;
+        reason: string;
+    }>;
+    /** Operator-facing run warnings (e.g. bridge.lbug write failed after contracts.json was written). */
+    warnings: string[];
     repoSnapshots: Record<string, RepoSnapshot>;
     /**
      * Matching stages this run was asked to skip. Populated on EVERY outcome,

package/dist/core/group/sync.js

@@ -13,6 +13,7 @@ import { ManifestExtractor } from './extractors/manifest-extractor.js';
 import { discoverWorkspaceLinks } from './extractors/workspace-extractor.js';
 import { buildProviderIndex, runExactMatch, runWildcardMatch } from './matching.js';
 import { detectServiceBoundaries, assignService } from './service-boundary-detector.js';
+import { applyDegradedFlag } from './normalization.js';
 import { getContractRegistryPath, readContractRegistry, writeContractRegistry } from './storage.js';
 import { markBridgeProvenanceUnknown, refreshPreservedBridgeMeta, writeBridgeUnlocked, } from './bridge-db.js';
 import { withGroupSyncLock } from './group-lock.js';
@@ -127,6 +128,8 @@ export function partitionManifestWindows(links, knownRepos, maxResident) {
 }
 export async function syncGroup(config, opts) {
     const missingRepos = [];
+    const failedRepos = [];
+    const warnings = [];
     // Repos that ARE registered but that we could not extract from — the index
     // would not open, or an extractor threw partway and the repo's staged
     // contracts were dropped. Kept separate from `missingRepos` because the two
@@ -309,6 +312,10 @@ export async function syncGroup(config, opts) {
                     // stack before logging it defeats the point.
                     logger.warn({ err, repo: regName, groupPath, lbugPath }, "⚠️ Could not read this repo's index; its contracts are omitted from this sync.");
                     unreadableRepos.push(groupPath);
+                    failedRepos.push({
+                        repo: groupPath,
+                        reason: err instanceof Error ? err.message : String(err),
+                    });
                     // Forget the handle recorded above (present only if the failure came
                     // after initLbug). Deferred manifest resolution derives its known-repo
                     // set from this map, so leaving the entry here re-opens a repo this
@@ -459,7 +466,7 @@ export async function syncGroup(config, opts) {
     // manifest-declared link can also emit a matchType:'exact' CrossLink with the
     // same endpoints. Prefer the manifest version — it reflects operator intent
     // and carries matchType:'manifest' which downstream consumers may rely on.
-    const crossLinks = dedupeCrossLinks([...manifestCrossLinks, ...matched, ...wildcard.matched]);
+    const crossLinks = dedupeCrossLinks([...manifestCrossLinks, ...matched, ...wildcard.matched]).map(applyDegradedFlag);
     const allContracts = autoContracts;
     const registry = {
         version: 1,
@@ -671,10 +678,12 @@ export async function syncGroup(config, opts) {
                             'a lower bound rather than as complete.'
                         : 'Its metadata could NOT be marked provenance-unknown, so those answers may still ' +
                             'report as complete despite describing an older sync.';
-                    logger.warn({ err: msg, groupDir, bridgeProvenanceWithdrawn: withdrawn }, '⚠️ writeBridge failed; contracts.json is intact and is the canonical copy, ' +
+                    const writeBridgeWarn = '⚠️ writeBridge failed; contracts.json is intact and is the canonical copy, ' +
                         'but bridge.lbug was not replaced: cross-repo queries may still answer from ' +
                         `the previous sync's contracts. ${provenanceNote} ` +
-                        'Re-run `gitnexus group sync` to retry.');
+                        'Re-run `gitnexus group sync` to retry.';
+                    logger.warn({ err: msg, groupDir, bridgeProvenanceWithdrawn: withdrawn }, writeBridgeWarn);
+                    warnings.push(writeBridgeWarn);
                 }
             }
         });
@@ -686,6 +695,9 @@ export async function syncGroup(config, opts) {
         unmatched: wildcard.remaining,
         missingRepos,
         unreadableRepos,
+        failedRepos,
+        warnings,
+        degradedLinks: crossLinks.filter((l) => l.degraded === true).length,
         repoSnapshots,
         registryOutcome,
     };

package/dist/core/group/types.d.ts

@@ -80,6 +80,19 @@ export interface CrossLink {
     contractId: string;
     matchType: MatchType;
     confidence: number;
+    /**
+     * `true` when the PROVIDER endpoint (`to`) has no resolved graph symbol —
+     * empty `symbolUid` / `symbolRef` at sync time (e.g. the handler failed to
+     * resolve and `symbolName` degraded to the file name). The contract boundary
+     * is still proven, but the link cannot anchor a cross-impact fan-out: an
+     * empty provider uid never matches a Phase-1 symbol id, and a downstream
+     * fan-out into it has no neighbor symbol to resolve. Derived once at the
+     * sync persistence boundary (`isUnresolvedEndpoint` in normalization.ts) and
+     * re-derived by `dedupeCrossLinks` when a merge backfills the uid. Absent on
+     * fully-anchored links. Distinct from manifest `manifest::…` synthetic UIDs,
+     * which have their own `fanout_status: 'not_attempted'` channel downstream.
+     */
+    degraded?: boolean;
 }
 export interface RepoSnapshot {
     indexedAt: string;

package/dist/core/ingestion/language-provider.d.ts

@@ -372,6 +372,15 @@ interface LanguageProviderConfig {
      * {@link extractModuleConstants} accepts.
      */
     readonly moduleConstantHeuristic?: (content: string) => boolean;
+    /**
+     * Prepare this language's harvested constants once the complete repo map is
+     * available and before route operands are folded. The parse phase passes only
+     * entries owned by this provider, so implementations can build one reusable
+     * language-specific index and may materialize deferred bindings in place.
+     *
+     * Default: undefined (the harvested constants are already fold-ready).
+     */
+    readonly prepareRouteConstants?: (repo: RepoConstants) => void;
     /**
      * Fold one file's non-literal route-path operand list
      * (`routePathExpr`/`routePathOperands` of an `ExtractedDecoratorRoute`)
@@ -723,6 +732,12 @@ export interface LanguageProvider extends Omit<LanguageProviderConfig, 'mroStrat
     /** Check if a name is a built-in/stdlib function that should be filtered from the call graph. */
     readonly isBuiltInName: (name: string) => boolean;
 }
+/**
+ * Run each provider's repo-constant preparation hook once over only the files
+ * that provider owns. Values are shared with `repo`, so in-place preparation
+ * is visible to the subsequent fold without copying the complete map.
+ */
+export declare function prepareRouteConstantsByProvider(repo: RepoConstants, providerForFile: (filePath: string) => Pick<LanguageProvider, 'prepareRouteConstants'> | null): void;
 /** Define a language provider — required fields must be supplied, optional fields get sensible defaults. */
 export declare function defineLanguage(config: LanguageProviderConfig): LanguageProvider;
 export {};

package/dist/core/ingestion/language-provider.js

@@ -45,6 +45,28 @@ export function shouldHarvestModuleConstants(provider, content) {
         return false;
     return !provider.moduleConstantHeuristic || provider.moduleConstantHeuristic(content);
 }
+/**
+ * Run each provider's repo-constant preparation hook once over only the files
+ * that provider owns. Values are shared with `repo`, so in-place preparation
+ * is visible to the subsequent fold without copying the complete map.
+ */
+export function prepareRouteConstantsByProvider(repo, providerForFile) {
+    const slices = new Map();
+    for (const [filePath, constants] of repo) {
+        const provider = providerForFile(filePath);
+        if (!provider?.prepareRouteConstants)
+            continue;
+        let slice = slices.get(provider);
+        if (!slice) {
+            slice = new Map();
+            slices.set(provider, slice);
+        }
+        slice.set(filePath, constants);
+    }
+    for (const [provider, slice] of slices) {
+        provider.prepareRouteConstants?.(slice);
+    }
+}
 const DEFAULTS = {
     mroStrategy: 'first-wins',
 };

package/dist/core/ingestion/languages/java.js

@@ -13,7 +13,7 @@ import { defineLanguage } from '../language-provider.js';
 import { createLeadingDocDescriptionExtractor } from '../utils/ast-helpers.js';
 import { javaTypeConfig } from '../type-extractors/jvm.js';
 import { extractSpringRoutes, extractSpringTypes } from '../route-extractors/spring.js';
-import { extractJavaModuleConstants, foldJavaOperands, isJavaConstantFile, } from '../route-extractors/java-const-resolver.js';
+import { extractJavaModuleConstants, foldJavaOperands, isJavaConstantFile, prepareJavaRouteConstants, } from '../route-extractors/java-const-resolver.js';
 import { javaExportChecker } from '../export-detection.js';
 import { createImportResolver } from '../import-resolvers/resolver-factory.js';
 import { javaImportConfig } from '../import-resolvers/configs/jvm.js';
@@ -202,11 +202,10 @@ export const javaProvider = defineLanguage({
     // INTERFACES on this side only, which cost the graph its Route nodes while
     // the group still published the contract).
     moduleConstantHeuristic: (content) => isJavaConstantFile(content) ||
-        // `import com.winning.opt.common.ApiPaths;` — ANY class import can bind a
-        // constant ref (`ApiPaths.X` at an annotation site), so gate on the
-        // general import shape, not on the imported name. Ingestion-only: this
-        // side needs the importing controller's own import table, which the group
-        // side instead derives lazily from the tree it already holds.
-        /\bimport\s+(?:static\s+)?[\w.]+\s*;/.test(content),
+        // Class imports and static (including on-demand) imports can bind a
+        // constant ref. Ordinary `import a.b.*;` is not a Java type import and is
+        // not expanded by extractJavaModuleConstants, so it must not harvest.
+        /\bimport\s+(?:static\s+[\w.]+(?:\.\*)?|[\w.]+)\s*;/.test(content),
+    prepareRouteConstants: prepareJavaRouteConstants,
     foldRoutePathOperands: foldJavaOperands,
 });

package/dist/core/ingestion/pipeline-phases/parse-impl.js

@@ -30,7 +30,8 @@ import { SCOPE_RESOLVERS } from '../scope-resolution/pipeline/registry.js';
 import { DATA_ROUTE_TABLE_SOURCE } from '../route-extractors/data-route-table.js';
 import { createWorkerPool, workerPoolDisabledByEnv, resolveAutoPoolSize, WorkerPoolInitializationError, WorkerPoolDisabledError, } from '../workers/worker-pool.js';
 import { normalizeExtractedRoutePath } from '../route-extractors/route-path.js';
-import { resolveOperands, } from '../route-extractors/python-const-resolver.js';
+import { resolveOperands } from '../route-extractors/python-const-resolver.js';
+import { prepareRouteConstantsByProvider } from '../language-provider.js';
 import { resolveInheritedSpringRoutes, } from '../route-extractors/spring-shared.js';
 import fs from 'node:fs';
 import { effectiveRamBytes, memoryAutopilotDisabled } from '../utils/effective-ram.js';
@@ -1022,6 +1023,10 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
         for (const { filePath, constants } of allModuleConstants) {
             repoConstants.set(filePath, constants);
         }
+        // Let each language prepare only its own constants slice before folding.
+        // This is where deferred wildcard bindings can be materialized once per
+        // provider without naming a language in the shared parse phase.
+        prepareRouteConstantsByProvider(repoConstants, getProviderForFile);
         const resolvedRoutes = [];
         let skipped = 0;
         for (const dr of allDecoratorRoutes) {

package/dist/core/ingestion/route-extractors/constant-resolver.d.ts

@@ -62,7 +62,23 @@ export interface ModuleConstants {
     readonly literals: Map<string, string>;
     readonly exprs: Map<string, readonly Operand[]>;
     readonly imports: Map<string, ImportBinding>;
+    /**
+     * On-demand (wildcard) import specifiers whose bound member names could not
+     * be enumerated at extract time — Java `import static a.b.C.*;`, Python
+     * `from m import *`. The agnostic fold never reads this (it has no way to
+     * enumerate a target module's exports); a language binding materializes the
+     * promised bindings from a repo-wide map after extraction — see
+     * `expandJavaWildcardStaticImports` in the Java binding — so they resolve
+     * through the plain `imports` path with no special cases in the fold.
+     */
+    readonly wildcardImports?: readonly string[];
 }
+/**
+ * Declaration keys a language extractor found but could not fold. Java and
+ * Kotlin both use this metadata to keep lower-priority imports from replacing
+ * a real local declaration; other producers simply return the empty set.
+ */
+export declare function unfoldableDeclarationsOf(mc: ModuleConstants | undefined): ReadonlySet<string>;
 /** Repo-wide map: unique file key (e.g. `app/constants.py`) → that file's
  * {@link ModuleConstants}. */
 export type RepoConstants = ReadonlyMap<string, ModuleConstants>;

package/dist/core/ingestion/route-extractors/constant-resolver.js

@@ -32,6 +32,16 @@ const MAX_RESOLVE_DEPTH = 8;
  * so we floor to `null` (skip) instead (#2393). The depth cap bounds recursion but
  * NOT output size, which grows multiplicatively; this bounds the output. */
 export const MAX_FOLD_LENGTH = 8192;
+const NO_UNFOLDABLE_DECLARATIONS = new Set();
+/**
+ * Declaration keys a language extractor found but could not fold. Java and
+ * Kotlin both use this metadata to keep lower-priority imports from replacing
+ * a real local declaration; other producers simply return the empty set.
+ */
+export function unfoldableDeclarationsOf(mc) {
+    const declarations = mc?.unfoldableDeclarations;
+    return declarations instanceof Set ? declarations : NO_UNFOLDABLE_DECLARATIONS;
+}
 /**
  * Fold an operand list to its concatenated literal, or `null` if any operand is
  * unresolvable (an unknown name, a non-string term, a cycle, or a depth overrun).

package/dist/core/ingestion/route-extractors/java-const-resolver.d.ts

@@ -42,6 +42,10 @@
 import type Parser from 'tree-sitter';
 import { type ImportResolver, type ModuleConstants, type Operand, type RepoConstants } from './constant-resolver.js';
 export type { ImportBinding, ModuleConstants, Operand, RepoConstants, } from './constant-resolver.js';
+export interface JavaModuleConstants extends ModuleConstants {
+    /** Declaration keys whose initializer exists but cannot be folded. */
+    readonly unfoldableDeclarations: ReadonlySet<string>;
+}
 export declare function isJavaConstantFile(source: string): boolean;
 /**
  * The Java {@link ImportResolver}: map a fully-qualified import specifier to
@@ -96,7 +100,7 @@ export declare function parseJavaConstOperands(node: Parser.SyntaxNode | null |
  * Last-wins in source order; a non-foldable rebind (`X = compute()`) drops X
  * to unresolvable rather than keeping a stale literal.
  */
-export declare function extractJavaModuleConstants(tree: Parser.Tree): ModuleConstants;
+export declare function extractJavaModuleConstants(tree: Parser.Tree): JavaModuleConstants;
 /**
  * Resolve a single Java constant referenced in `fileKey` to its literal string
  * value, folding `+` concatenation and following import chains via
@@ -112,3 +116,25 @@ export declare function resolveJavaConstant(fileKey: string, name: string, repo:
  * `fileKey`, or null when any piece is unresolvable (skip floor).
  */
 export declare function foldJavaOperands(fileKey: string, operands: readonly Operand[], repo: RepoConstants): string | null;
+/**
+ * Constant-defining file keys used by Java import resolution.
+ *
+ * Build once per repo pass. Recomputing this set for every wildcard-importing
+ * controller makes expansion quadratic in controller count.
+ */
+export declare function buildJavaConstantKeys(repo: RepoConstants): ReadonlySet<string>;
+export interface JavaConstantIndex {
+    readonly keys: ReadonlySet<string>;
+    /** Every resolvable path suffix as a dotted module name; null means ambiguous. */
+    readonly byModule: ReadonlyMap<string, string | null>;
+    /** Direct members by constant-defining file, built once for all importers. */
+    readonly membersByFile: ReadonlyMap<string, ReadonlySet<string>>;
+}
+/**
+ * Build all Java import suffixes once, turning repeated wildcard target lookup
+ * from O(importers × constant files) into O(path segments + importers).
+ */
+export declare function buildJavaConstantIndex(repo: RepoConstants): JavaConstantIndex;
+export declare function expandJavaWildcardStaticImports(mc: ModuleConstants, _fileKey: string, repo: RepoConstants, index?: JavaConstantIndex): ModuleConstants;
+/** Prepare every Java constants entry with one shared suffix index. */
+export declare function prepareJavaRouteConstants(repo: RepoConstants): JavaConstantIndex;