gitnexus 1.6.11-rc.8 → 1.6.11

package/dist/core/ingestion/route-extractors/spring-shared.d.ts

@@ -21,10 +21,26 @@ import type Parser from 'tree-sitter';
  *
  * `@RequestMapping` is intentionally absent: on a method it carries no implicit
  * verb (the verb lives in its `method = RequestMethod.X` attribute), and on a
- * class it is a URL prefix rather than a route. Callers handle `@RequestMapping`
+ * class it is a URL prefix rather than a route. Callers handle `RequestMapping`
  * separately.
  */
 export declare const METHOD_ANNOTATION_TO_HTTP: Record<string, string>;
+/**
+ * Resolve a REGISTERED vendor-derived Spring mapping annotation to its base.
+ *
+ * Vendor definitions often live in binary dependencies, so their Spring
+ * meta-annotations cannot be inspected from repository source. Resolution uses
+ * the conventional `<vendorPrefix><baseAnnotation>` name instead.
+ *
+ * Suffix matching alone accepted unrelated annotations (`@AuditPostMapping`
+ * produced a phantom route — review P2). Resolution now requires the name to
+ * be `<registeredPrefix><base>` with the prefix drawn from a small registry:
+ * `Win` by default (Winning Health), extendable via
+ * `GITNEXUS_SPRING_VENDOR_PREFIXES=Win,Acme,Other`. Changing the registry
+ * invalidates persisted JVM route evidence on the next analysis. Exact-known
+ * Spring annotation names return `undefined`; callers handle those directly.
+ */
+export declare function resolveSpringAnnotationAlias(annotationName: string): string | undefined;
 /**
  * Resolve a method-level Spring mapping annotation to its HTTP method(s).
  *
@@ -32,8 +48,21 @@ export declare const METHOD_ANNOTATION_TO_HTTP: Record<string, string>;
  * one or more static `RequestMethod.X` values; when its `method` member is
  * absent or an empty array, `'*'` preserves Spring's method-agnostic semantics.
  * A present but non-static method expression yields no methods (fail closed).
+ *
+ * Vendor-derived aliases (e.g. `@WinPostMapping`) are resolved by suffix to
+ * their base annotation before the above logic applies — see
+ * {@link resolveSpringAnnotationAlias}.
  */
 export declare function springAnnotationHttpMethods(annotationName: string, annotationText: string): readonly string[];
+/**
+ * True when an annotation name is a class-level request-mapping annotation —
+ * either Spring's own `@RequestMapping` or a registered vendor alias that
+ * resolves to it (`@WinRequestMapping`). Class-level handling in both the
+ * group extractor and the ingestion route extractor routes through this
+ * predicate so vendor aliases get the same prefix/constraint semantics as
+ * the base annotation (review P1).
+ */
+export declare function isClassLevelMappingAnnotation(annotationName: string): boolean;
 /** Intersect class- and method-level Spring mapping constraints. */
 export declare function intersectSpringHttpMethods(classMethods: readonly string[], methodMethods: readonly string[]): readonly string[];
 /**

package/dist/core/ingestion/route-extractors/spring-shared.js

@@ -16,12 +16,13 @@
  * `group/` to avoid a dependency cycle.
  */
 import { parseSpringAnnotationArguments } from '../frameworks/spring/annotation-arguments.js';
+import { springVendorPrefixes } from '../frameworks/spring/vendor-prefixes.js';
 /**
  * Spring shortcut method-annotation → HTTP verb.
  *
  * `@RequestMapping` is intentionally absent: on a method it carries no implicit
  * verb (the verb lives in its `method = RequestMethod.X` attribute), and on a
- * class it is a URL prefix rather than a route. Callers handle `@RequestMapping`
+ * class it is a URL prefix rather than a route. Callers handle `RequestMapping`
  * separately.
  */
 export const METHOD_ANNOTATION_TO_HTTP = {
@@ -32,7 +33,44 @@ export const METHOD_ANNOTATION_TO_HTTP = {
     PatchMapping: 'PATCH',
 };
 /**
- * Parse one `RequestMethod.X` literal or a Java annotation array of literals.
+ * All recognised Spring mapping-annotation simple names (shortcut + base).
+ * Sorted longest-first so {@link resolveSpringAnnotationAlias} prefers the most
+ * specific suffix (e.g. `PostMapping` before any hypothetical shorter overlap).
+ */
+const SPRING_MAPPING_NAMES = [
+    ...Object.keys(METHOD_ANNOTATION_TO_HTTP),
+    'RequestMapping',
+].sort((a, b) => b.length - a.length);
+/**
+ * Resolve a REGISTERED vendor-derived Spring mapping annotation to its base.
+ *
+ * Vendor definitions often live in binary dependencies, so their Spring
+ * meta-annotations cannot be inspected from repository source. Resolution uses
+ * the conventional `<vendorPrefix><baseAnnotation>` name instead.
+ *
+ * Suffix matching alone accepted unrelated annotations (`@AuditPostMapping`
+ * produced a phantom route — review P2). Resolution now requires the name to
+ * be `<registeredPrefix><base>` with the prefix drawn from a small registry:
+ * `Win` by default (Winning Health), extendable via
+ * `GITNEXUS_SPRING_VENDOR_PREFIXES=Win,Acme,Other`. Changing the registry
+ * invalidates persisted JVM route evidence on the next analysis. Exact-known
+ * Spring annotation names return `undefined`; callers handle those directly.
+ */
+export function resolveSpringAnnotationAlias(annotationName) {
+    const registeredVendorPrefixes = springVendorPrefixes();
+    for (const base of SPRING_MAPPING_NAMES) {
+        if (annotationName.length > base.length && annotationName.endsWith(base)) {
+            const prefix = annotationName.slice(0, annotationName.length - base.length);
+            if (registeredVendorPrefixes.has(prefix)) {
+                return base;
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Parse one `RequestMethod.X` literal or a Java `{…}` / Kotlin `[…]` array of
+ * those literals.
  * An empty array is valid and means Spring's unrestricted/default method set.
  * Runtime expressions fail closed instead of producing a guessed route.
  */
@@ -59,18 +97,23 @@ function parseRequestMethodValues(value) {
         }
         trimmed += char;
     }
-    const hasOpeningBrace = trimmed.startsWith('{');
-    const hasClosingBrace = trimmed.endsWith('}');
-    if (hasOpeningBrace !== hasClosingBrace)
+    const wrapped = (trimmed.startsWith('{') && trimmed.endsWith('}')) ||
+        (trimmed.startsWith('[') && trimmed.endsWith(']'));
+    if (!wrapped &&
+        (trimmed.startsWith('{') ||
+            trimmed.startsWith('[') ||
+            trimmed.endsWith('}') ||
+            trimmed.endsWith(']'))) {
         return null;
-    const body = hasOpeningBrace ? trimmed.slice(1, -1).trim() : trimmed;
+    }
+    const body = wrapped ? trimmed.slice(1, -1).trim() : trimmed;
     if (body.length === 0)
         return [];
-    if (!hasOpeningBrace && body.includes(','))
+    if (!wrapped && body.includes(','))
         return null;
     const methods = [];
     const parts = body.split(',');
-    if (hasOpeningBrace && parts[parts.length - 1].trim() === '')
+    if (wrapped && parts[parts.length - 1].trim() === '')
         parts.pop();
     for (const rawPart of parts) {
         const part = rawPart.trim();
@@ -89,12 +132,24 @@ function parseRequestMethodValues(value) {
  * one or more static `RequestMethod.X` values; when its `method` member is
  * absent or an empty array, `'*'` preserves Spring's method-agnostic semantics.
  * A present but non-static method expression yields no methods (fail closed).
+ *
+ * Vendor-derived aliases (e.g. `@WinPostMapping`) are resolved by suffix to
+ * their base annotation before the above logic applies — see
+ * {@link resolveSpringAnnotationAlias}.
  */
 export function springAnnotationHttpMethods(annotationName, annotationText) {
+    // Exact shortcut match (PostMapping → POST, etc.)
     const shortcut = METHOD_ANNOTATION_TO_HTTP[annotationName];
     if (shortcut)
         return [shortcut];
-    if (annotationName !== 'RequestMapping')
+    // Resolve vendor alias by suffix (WinPostMapping → PostMapping, etc.)
+    const base = resolveSpringAnnotationAlias(annotationName) ?? annotationName;
+    // Alias of a shortcut annotation
+    const aliasShortcut = METHOD_ANNOTATION_TO_HTTP[base];
+    if (aliasShortcut)
+        return [aliasShortcut];
+    // Direct or aliased @RequestMapping: parse the method= attribute
+    if (base !== 'RequestMapping')
         return [];
     const args = parseSpringAnnotationArguments(annotationText);
     if (args === null)
@@ -109,6 +164,19 @@ export function springAnnotationHttpMethods(annotationName, annotationText) {
         return [];
     return methods.length > 0 ? methods : ['*'];
 }
+/**
+ * True when an annotation name is a class-level request-mapping annotation —
+ * either Spring's own `@RequestMapping` or a registered vendor alias that
+ * resolves to it (`@WinRequestMapping`). Class-level handling in both the
+ * group extractor and the ingestion route extractor routes through this
+ * predicate so vendor aliases get the same prefix/constraint semantics as
+ * the base annotation (review P1).
+ */
+export function isClassLevelMappingAnnotation(annotationName) {
+    if (annotationName === 'RequestMapping')
+        return true;
+    return resolveSpringAnnotationAlias(annotationName) === 'RequestMapping';
+}
 /** Intersect class- and method-level Spring mapping constraints. */
 export function intersectSpringHttpMethods(classMethods, methodMethods) {
     if (classMethods.length === 0 || methodMethods.length === 0)

package/dist/core/ingestion/route-extractors/spring.js

@@ -20,7 +20,7 @@
  */
 import Parser from 'tree-sitter';
 import Java from 'tree-sitter-java';
-import { intersectSpringHttpMethods, springAnnotationHttpMethods, isRouteMemberKey, findEnclosingType, unquoteSpringLiteral, } from './spring-shared.js';
+import { intersectSpringHttpMethods, springAnnotationHttpMethods, isRouteMemberKey, findEnclosingType, isClassLevelMappingAnnotation, unquoteSpringLiteral, } from './spring-shared.js';
 import { parseJavaConstOperands } from './java-const-resolver.js';
 /**
  * Single predicate-free tree-sitter query that captures all route annotations
@@ -172,7 +172,8 @@ export function extractSpringRoutes(tree, filePath, lineOffset = 0) {
         if (!annNode || !node || (!valueNode && !valueExprNode))
             continue;
         const capturedAnnotationName = annNode.text.split('.').pop() ?? annNode.text;
-        if (node.type === 'class_declaration' && capturedAnnotationName === 'RequestMapping') {
+        if (node.type === 'class_declaration' &&
+            isClassLevelMappingAnnotation(capturedAnnotationName)) {
             if (!isRouteMemberKey(keyNode))
                 continue;
             if (!valueNode) {
@@ -420,12 +421,15 @@ function annotationHasRouteMember(ann) {
 }
 /** Static class/interface-level RequestMapping method constraint, or wildcard by default. */
 function typeRequestMethods(typeNode) {
-    const mappings = declarationAnnotations(typeNode).filter((ann) => annotationName(ann) === 'RequestMapping');
+    const mappings = declarationAnnotations(typeNode).filter((ann) => isClassLevelMappingAnnotation(annotationName(ann) ?? ''));
     if (mappings.length === 0)
         return ['*'];
     if (mappings.length !== 1)
         return [];
-    return springAnnotationHttpMethods('RequestMapping', mappings[0].text);
+    const mappingName = annotationName(mappings[0]);
+    if (!mappingName)
+        return [];
+    return springAnnotationHttpMethods(mappingName, mappings[0].text);
 }
 function annotationRoutePathsOrDefault(ann) {
     const paths = annotationRoutePaths(ann);
@@ -437,7 +441,7 @@ function annotationRoutePathsOrDefault(ann) {
 function typeClassPrefixes(typeNode) {
     const prefixes = [];
     for (const ann of declarationAnnotations(typeNode)) {
-        if (annotationName(ann) === 'RequestMapping')
+        if (isClassLevelMappingAnnotation(annotationName(ann) ?? ''))
             prefixes.push(...annotationRoutePaths(ann));
     }
     return prefixes;

package/dist/core/ingestion/scope-extractor.js

@@ -1031,6 +1031,11 @@ function pass5CollectReferences(matches, positionIndex, filePath, referenceSites
         // detection knows what to do with that. Absent for every language without
         // pointer embedding, so their sites stay byte-identical.
         const embeddedAsPointer = match['@reference.embedded-pointer'] !== undefined;
+        // Static-gating marker: the call sits in a branch the language layer proved
+        // dead at index time (Zig `if (CONST_FALSE)`). Recorded on the site and
+        // copied to the CALLS edge; absent everywhere else (see
+        // `ReferenceSite.staticGated`).
+        const staticGated = kind === 'call' && match['@reference.static-gated'] !== undefined;
         const site = {
             name: nameCap.text,
             atRange: anchor.range,
@@ -1051,6 +1056,7 @@ function pass5CollectReferences(matches, positionIndex, filePath, referenceSites
             ...(receiverChain !== undefined ? { receiverChain } : {}),
             ...(inCalleePosition ? { inCalleePosition: true } : {}),
             ...(embeddedAsPointer ? { embeddedAsPointer: true } : {}),
+            ...(staticGated ? { staticGated: true } : {}),
         };
         referenceSites.push(site);
     }
@@ -1450,6 +1456,7 @@ const KNOWN_SUB_TAGS = new Set([
     '@scope.lexical-names',
     '@declaration.name',
     '@declaration.qualified_name',
+    '@declaration.is-synthetic',
     '@import.name',
     '@import.source',
     '@import.alias',
@@ -1468,6 +1475,7 @@ const KNOWN_SUB_TAGS = new Set([
     '@reference.property-key',
     '@reference.callee-position',
     '@reference.embedded-pointer',
+    '@reference.static-gated',
     '@reference.receiver',
     '@reference.operator',
     '@reference.arity',

package/dist/core/ingestion/scope-resolution/contract/scope-resolver.d.ts

@@ -780,6 +780,68 @@ export interface ScopeResolver {
      * Swift — opt in.
      */
     readonly constructorCallTargetsClass?: boolean;
+    /**
+     * When true, the CALLS edge emitted for a constructor-form site
+     * (`callForm === 'constructor'`) carries ` (constructor)` appended to its
+     * `reason` — `local-call (constructor)`, `import-resolved (constructor)`,
+     * `scope-resolution: call (constructor)` — so a consumer can tell
+     * "constructs an instance of" apart from "invokes" on the edge alone.
+     *
+     * Opt-in because the unsuffixed strings are a pinned contract: the legacy
+     * DAG vocabulary (`'import-resolved' | 'local-call' | …`, see the
+     * same-graph guarantee above) is asserted verbatim by consumers and by the
+     * per-language resolver suites, constructor sites included. A language
+     * that links a construction site to the TYPE node itself — a struct
+     * literal `T{…}` in Zig, where nothing but the marker distinguishes the
+     * edge from an invocation in the schema (PR #1432 review) — opts in; the
+     * default leaves every existing edge byte-identical.
+     *
+     * The marker rides in `reason` because relationships carry no arbitrary
+     * properties (adding one moves SCHEMA_FINGERPRINT — the IMPLEMENTS
+     * `-pointer` precedent in `pipeline/run.ts`). Applies to the free-call
+     * fallback, the reference bridge and the receiver-bound paths — a
+     * namespace-qualified literal (`mod.T{…}`, Case 1), a type nested in the
+     * receiver's class (`A.Item{}`, Case 2) and a dotted type binding (Case 3)
+     * all go through `constructionSiteReason` — so an opted-in provider sees
+     * one vocabulary whichever path resolved the site.
+     */
+    readonly markConstructionSites?: boolean;
+    /**
+     * When true, a namespace's exported member may also be a name the target
+     * module IMPORTED and publishes as its own — the hub-module shape, a file
+     * made only of re-exports (`pub const Terminal = @import("Terminal.zig");`,
+     * `pub const Thing = @import("thing.zig").Thing;`). Such a file owns no
+     * local binding, so the default local-only export lookup
+     * (`findExportedDef`) finds nothing for `terminal.Terminal.init()`,
+     * `t: stdx.Thing`, `var p = stdx.PRNG.from_seed()` or `var a:
+     * stdx.BoundedArrayType(u8, 4)`, and the receiver-bound namespace paths
+     * (Case 1, Case 3, the compound resolver's namespace branch) fall through.
+     * With the flag those paths use `findExportedDefIncludingImportedNames`,
+     * which reads the finalized channel where the published names live.
+     *
+     * Off by default: in most languages a module's imports are not its exports
+     * (TypeScript `import { X }` publishes nothing), and the finalized edge does
+     * not record whether the import was written `pub`. Zig opts in — a hub
+     * member a consumer can name through the hub is public by construction.
+     */
+    readonly namespaceExportsIncludeImportedNames?: boolean;
+    /**
+     * When true, a qualified receiver is walked SEGMENT BY SEGMENT from its
+     * verified namespace root instead of being split once at the last dot:
+     * `hub.sub.Thing{}` (a namespace republished by a hub — `pub const sub =
+     * @import("sub.zig");`), `mod.Outer.Inner{}` (a type nested in a type),
+     * `opmod.Op.lookup` (an enum variant reached through the module), and the
+     * typed forms `x: mod.Outer.Inner`. Each hop is either a class-like member
+     * of the current module(s) / the current class, or a namespace import
+     * edge the current module's scope binds under that name; a hop that is
+     * ambiguous — two files behind one handle disagree, or a name is both a
+     * type and a republished module — resolves nothing rather than picking a
+     * first match. Off, the receiver-bound paths (Case 1, Case 2's
+     * namespace-qualified class, Case 3) keep their one-hop lookups exactly
+     * as they are, so no existing edge moves; Zig opts in (PR #1432 review,
+     * 8.10), whose module system is nothing but nested `const` handles.
+     */
+    readonly resolveNamespaceChains?: boolean;
     /**
      * How this language spells a construction expression, so the compound
      * receiver resolver can type an INLINE constructor receiver — the

package/dist/core/ingestion/scope-resolution/graph-bridge/edges.d.ts

@@ -55,6 +55,8 @@ export declare function tryEmitEdge(graph: KnowledgeGraph, scopes: ScopeResoluti
     /** See {@link isPhantomCalleeRead}. Set by the extractor from the
      *  language's `@reference.callee-position` marker; absent otherwise. */
     readonly inCalleePosition?: boolean;
+    /** See `ReferenceSite.staticGated`; copied onto the emitted edge. */
+    readonly staticGated?: boolean;
 }, targetDef: SymbolDefinition, reason: string, seen: Set<string>, confidence?: number, collapseByCallerTarget?: boolean, calleeCapture?: CalleeIdCaptureCtx): boolean;
 /**
  * Variant of `tryEmitEdge` that takes a pre-resolved target graph id
@@ -85,4 +87,6 @@ export declare function tryEmitEdgeWithExplicitTargetId(graph: KnowledgeGraph, s
         startCol: number;
     };
     readonly kind: string;
+    /** See `ReferenceSite.staticGated`; copied onto the emitted edge. */
+    readonly staticGated?: boolean;
 }, targetGraphId: string, reason: string, seen: Set<string>, confidence?: number, collapseByCallerTarget?: boolean, calleeCapture?: CalleeIdCaptureCtx): boolean;

package/dist/core/ingestion/scope-resolution/graph-bridge/edges.js

@@ -133,6 +133,7 @@ export function tryEmitEdge(graph, scopes, nodeLookup, site, targetDef, reason,
         type: edgeType,
         confidence,
         reason,
+        ...(site.staticGated === true ? { staticGated: true } : {}),
     });
     return true;
 }
@@ -184,6 +185,7 @@ export function tryEmitEdgeWithExplicitTargetId(graph, scopes, nodeLookup, site,
         type: edgeType,
         confidence,
         reason,
+        ...(site.staticGated === true ? { staticGated: true } : {}),
     });
     return true;
 }

package/dist/core/ingestion/scope-resolution/graph-bridge/ids.js

@@ -22,6 +22,15 @@ import { isOverloadableCallable, isPositionQualifiedLocalLabel, } from '../../ut
 import { templateConstraintsIdTag } from '../../utils/template-arguments.js';
 import { parameterShapeIdTag } from '../../utils/method-props.js';
 import { definitionIdPosition } from '../utils/definition-id.js';
+const defGraphIdMemoByLookup = new WeakMap();
+const isResolveDefGraphIdMemoEnabled = () => {
+    const raw = process.env.GITNEXUS_RESOLVE_DEF_GRAPH_ID_MEMO;
+    if (raw === undefined || raw.trim() === '')
+        return true;
+    const value = raw.trim().toLowerCase();
+    return value !== '0' && value !== 'false' && value !== 'off' && value !== 'no';
+};
+const defGraphIdMemoKey = (filePath, def) => `${filePath}\0${def.nodeId ?? ''}\0${def.type ?? ''}\0${def.qualifiedName ?? ''}\0${def.parameterCount ?? ''}\0${(def.parameterTypes ?? []).join(',')}\0${(def.parameterTypeClasses ?? []).join(',')}\0${def.namespacePrefix ?? ''}\0${(def.templateArguments ?? []).join(',')}\0${templateConstraintsIdTag(def.templateConstraints)}`;
 /**
  * Labels that may legitimately ANCHOR a CALLS/ACCESSES edge as the
  * source ("caller"). A Variable / Property can be the TARGET of an
@@ -188,6 +197,25 @@ function siblingCallableLabel(label) {
     return undefined;
 }
 export function resolveDefGraphId(filePath, def, nodeLookup) {
+    if (!isResolveDefGraphIdMemoEnabled()) {
+        return resolveDefGraphIdUncached(filePath, def, nodeLookup);
+    }
+    const qn = def.qualifiedName;
+    if (qn === undefined || qn.length === 0)
+        return undefined;
+    let bucket = defGraphIdMemoByLookup.get(nodeLookup);
+    if (bucket === undefined) {
+        bucket = new Map();
+        defGraphIdMemoByLookup.set(nodeLookup, bucket);
+    }
+    const key = defGraphIdMemoKey(filePath, def);
+    if (bucket.has(key))
+        return bucket.get(key);
+    const resolved = resolveDefGraphIdUncached(filePath, def, nodeLookup);
+    bucket.set(key, resolved);
+    return resolved;
+}
+function resolveDefGraphIdUncached(filePath, def, nodeLookup) {
     const qn = def.qualifiedName;
     if (qn === undefined || qn.length === 0)
         return undefined;

package/dist/core/ingestion/scope-resolution/graph-bridge/node-lookup.js

@@ -246,6 +246,15 @@ export const LINKABLE_LABELS = new Set([
     // are unreachable and label-agnostic fallback can alias it to a same-named
     // Constructor or Method (#2801).
     'Record',
+    // Union is linkable because Zig wires `union` / `union(enum)` as a member
+    // container: the definition phase emits HAS_METHOD / HAS_PROPERTY edges FROM
+    // the Union node (`union_declaration` in MEMBER_OWNER_NODE_TYPES) and the
+    // scope side dispatches methods on union receivers (`main → isEnergy` in
+    // test/integration/resolvers/zig.test.ts). Without this entry the schema
+    // never declares a `FROM Union` pair and `analyze` aborts on the first Zig
+    // repo that declares a union (reproduced on the zig-basic fixture itself).
+    // Also lets `Tag{ .energy = 5 }` constructor references bridge to the node.
+    'Union',
     // Trait nodes are linkable so MRO builders can bridge PHP/Rust trait
     // defs between scope-resolution DefIds and the graph's node ids.
     // IMPLEMENTS edges from classes to traits are otherwise invisible to
@@ -261,8 +270,8 @@ export const LINKABLE_LABELS = new Set([
     //
     // Covers every language that spells an alias this way — TypeScript, Kotlin,
     // Dart and Rust all emit `@declaration.type_alias`. The remaining
-    // `CLASS_KINDS` entries (Typedef, Record, Union, Delegate, Annotation,
-    // Template) plausibly have the same gap, but nothing exercises them today
+    // `CLASS_KINDS` entries (Typedef, Delegate, Annotation, Template, Namespace)
+    // plausibly have the same gap, but nothing exercises them today
     // and adding labels no test covers is how this list drifts out of sync with
     // what it claims.
     'TypeAlias',

package/dist/core/ingestion/scope-resolution/graph-bridge/references-to-edges.d.ts

@@ -6,7 +6,7 @@
  *      chain looking for an enclosing Function/Method/Class.
  *   2. Resolve `toDef` → target graph-node id via `nodeLookup`.
  *   3. Emit the edge (`CALLS` / `READS` / `WRITES` / `EXTENDS` / `USES`)
- *      with the standard reason format.
+ *      with the standard reason format (`referenceEdgeReason`).
  *
  * Skips (without throwing) when either side fails to map — either side
  * may legitimately not exist as a graph node (e.g. a resolved target
@@ -30,6 +30,27 @@ import type { CalleeIdSink } from '../graph-bridge/callee-id-sink.js';
  * `${filePath}:${startLine}:${startCol}`.
  */
 type ReferenceSiteSkipSet = ReadonlySet<string>;
+export interface EmitReferencesOptions {
+    /** When true, a constructor-form call site's edge gets ` (constructor)`
+     *  appended to its reason. See `ScopeResolver.markConstructionSites`. */
+    readonly markConstructionSites?: boolean;
+}
+/**
+ * `reason` of the edge a resolved reference emits: `scope-resolution: <kind>`,
+ * plus ` (constructor)` for a construction site when the provider opted in —
+ * a struct literal (`T{…}` in Zig, `T { .. }` in Rust, `T{}` in Go) or a
+ * `new T()` resolves to the type (or its constructor) as a CALLS edge exactly
+ * like an invocation does, and nothing else on the edge tells the two apart
+ * (PR #1432 review).
+ *
+ * The marker rides in `reason` because relationships carry no arbitrary
+ * properties — adding one would change the relation DDL and move
+ * SCHEMA_FINGERPRINT (see the IMPLEMENTS `-pointer` precedent in
+ * `pipeline/run.ts`). The plain `scope-resolution: call` prefix is kept, so a
+ * consumer matching the prefix still sees every call; one matching the exact
+ * string sees invocations only.
+ */
+export declare function referenceEdgeReason(ref: Pick<Reference, 'kind' | 'callForm'>, markConstructionSites: boolean | undefined): string;
 /**
  * Value labels whose defs MAY be function-local. A reference to one of these is
  * dropped only when the def is positively identified as living inside a function
@@ -65,7 +86,7 @@ calleeIdSink?: CalleeIdSink,
  *
  * Optional so callers that never capture bare identifiers are unchanged.
  */
-functionLocalValueDefIds?: ReadonlySet<string>): {
+functionLocalValueDefIds?: ReadonlySet<string>, options?: EmitReferencesOptions): {
     emitted: number;
     skipped: number;
 };

package/dist/core/ingestion/scope-resolution/graph-bridge/references-to-edges.js

@@ -6,7 +6,7 @@
  *      chain looking for an enclosing Function/Method/Class.
  *   2. Resolve `toDef` → target graph-node id via `nodeLookup`.
  *   3. Emit the edge (`CALLS` / `READS` / `WRITES` / `EXTENDS` / `USES`)
- *      with the standard reason format.
+ *      with the standard reason format (`referenceEdgeReason`).
  *
  * Skips (without throwing) when either side fails to map — either side
  * may legitimately not exist as a graph node (e.g. a resolved target
@@ -20,6 +20,26 @@
 import { resolveCallerGraphId, resolveDefGraphId } from '../graph-bridge/ids.js';
 import { mapReferenceKindToEdgeType } from '../graph-bridge/edges.js';
 import { isValueDefinitionLabel } from '../../utils/ast-helpers.js';
+/**
+ * `reason` of the edge a resolved reference emits: `scope-resolution: <kind>`,
+ * plus ` (constructor)` for a construction site when the provider opted in —
+ * a struct literal (`T{…}` in Zig, `T { .. }` in Rust, `T{}` in Go) or a
+ * `new T()` resolves to the type (or its constructor) as a CALLS edge exactly
+ * like an invocation does, and nothing else on the edge tells the two apart
+ * (PR #1432 review).
+ *
+ * The marker rides in `reason` because relationships carry no arbitrary
+ * properties — adding one would change the relation DDL and move
+ * SCHEMA_FINGERPRINT (see the IMPLEMENTS `-pointer` precedent in
+ * `pipeline/run.ts`). The plain `scope-resolution: call` prefix is kept, so a
+ * consumer matching the prefix still sees every call; one matching the exact
+ * string sees invocations only.
+ */
+export function referenceEdgeReason(ref, markConstructionSites) {
+    return markConstructionSites === true && ref.kind === 'call' && ref.callForm === 'constructor'
+        ? 'scope-resolution: call (constructor)'
+        : `scope-resolution: ${ref.kind}`;
+}
 /**
  * Value labels whose defs MAY be function-local. A reference to one of these is
  * dropped only when the def is positively identified as living inside a function
@@ -53,7 +73,7 @@ calleeIdSink,
  *
  * Optional so callers that never capture bare identifiers are unchanged.
  */
-functionLocalValueDefIds) {
+functionLocalValueDefIds, options) {
     let emitted = 0;
     let skipped = 0;
     const seen = new Set();
@@ -119,7 +139,8 @@ functionLocalValueDefIds) {
                 targetId: targetGraphId,
                 type: edgeType,
                 confidence: ref.confidence,
-                reason: `scope-resolution: ${ref.kind}`,
+                reason: referenceEdgeReason(ref, options?.markConstructionSites),
+                ...(ref.staticGated === true ? { staticGated: true } : {}),
             });
             emitted++;
         }

package/dist/core/ingestion/scope-resolution/passes/callable-value-flow.d.ts

@@ -3,7 +3,7 @@
  * values. Providers own syntax recognition; this pass consumes only the
  * JSON-safe facts carried by ParsedFile.
  */
-import type { ParsedFile, SymbolDefinition } from '../../../../_shared/index.js';
+import type { CallableFlowExpectedSignature, ParsedFile, SymbolDefinition } from '../../../../_shared/index.js';
 import type { KnowledgeGraph } from '../../../graph/types.js';
 import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js';
 import type { GraphNodeLookup } from '../graph-bridge/node-lookup.js';
@@ -44,6 +44,14 @@ export interface EmitCallableValueFlowInput {
     readonly isCallableValueTarget?: (def: SymbolDefinition) => boolean;
     readonly hasFileLocalCallableLinkage?: (def: SymbolDefinition) => boolean;
     readonly onWarn?: (warning: CallableValueFlowWarning) => void;
+    /** When set, skip a second `collectDeferredIndirectSites` walk. */
+    readonly deferredIndirectSites?: ReadonlySet<string>;
+    /** When set, skip a second `referenceSites` signature walk. */
+    readonly callSignaturesBySite?: ReadonlyMap<string, CallableFlowExpectedSignature>;
+}
+export interface DeferredIndirectCollection {
+    readonly sites: ReadonlySet<string>;
+    readonly callSignaturesBySite: ReadonlyMap<string, CallableFlowExpectedSignature>;
 }
 /** Position key shared with the existing free/reference skip-set contract. */
 export declare function callableFlowSiteKey(filePath: string, range: {
@@ -55,6 +63,8 @@ export declare function callableFlowSiteKey(filePath: string, range: {
  * Malformed/stale facts never suppress ordinary resolution.
  */
 export declare function collectDeferredIndirectSites(parsedFiles: readonly ParsedFile[], scopes?: ScopeResolutionIndexes): ReadonlySet<string>;
+/** One `referenceSites` walk for deferred keys and call-signature evidence. */
+export declare function collectDeferredIndirectCollection(parsedFiles: readonly ParsedFile[], scopes?: ScopeResolutionIndexes): DeferredIndirectCollection;
 export declare function emitCallableValueFlow(input: EmitCallableValueFlowInput): CallableValueFlowResult;
 /**
  * Pure — exported for `bench/callable-value-flow/measure.mjs`, which guards its

package/dist/core/ingestion/scope-resolution/passes/callable-value-flow.js

@@ -28,7 +28,12 @@ export function callableFlowSiteKey(filePath, range) {
  * Malformed/stale facts never suppress ordinary resolution.
  */
 export function collectDeferredIndirectSites(parsedFiles, scopes) {
+    return collectDeferredIndirectCollection(parsedFiles, scopes).sites;
+}
+/** One `referenceSites` walk for deferred keys and call-signature evidence. */
+export function collectDeferredIndirectCollection(parsedFiles, scopes) {
     const out = new Set();
+    const callSignaturesBySite = new Map();
     const flowCells = new Set();
     if (scopes !== undefined) {
         for (const parsed of parsedFiles) {
@@ -41,9 +46,24 @@ export function collectDeferredIndirectSites(parsedFiles, scopes) {
         }
     }
     for (const parsed of parsedFiles) {
-        const canonical = new Set(parsed.referenceSites
-            .filter((site) => site.kind === 'call')
-            .map((site) => callableFlowSiteKey(parsed.filePath, site.atRange)));
+        const canonical = new Set();
+        for (const site of parsed.referenceSites) {
+            if (site.kind !== 'call')
+                continue;
+            const key = callableFlowSiteKey(parsed.filePath, site.atRange);
+            canonical.add(key);
+            const signature = {
+                ...(site.arity !== undefined ? { parameterCount: site.arity } : {}),
+                ...(site.argumentTypes !== undefined ? { parameterTypes: site.argumentTypes } : {}),
+                ...(site.argumentTypeClasses !== undefined
+                    ? { parameterTypeClasses: site.argumentTypeClasses }
+                    : {}),
+            };
+            const previous = callSignaturesBySite.get(key);
+            if (previous === undefined || signatureEvidence(signature) > signatureEvidence(previous)) {
+                callSignaturesBySite.set(key, signature);
+            }
+        }
         for (const site of parsed.callableFlowSites ?? []) {
             if (site.kind !== 'invoke')
                 continue;
@@ -58,7 +78,7 @@ export function collectDeferredIndirectSites(parsedFiles, scopes) {
             }
         }
     }
-    return out;
+    return { sites: out, callSignaturesBySite };
 }
 function flowCellOperand(site) {
     switch (site.kind) {
@@ -80,7 +100,7 @@ function flowCellOperand(site) {
 export function emitCallableValueFlow(input) {
     const facts = [];
     const invokes = [];
-    const canonicalInvokeKeys = collectDeferredIndirectSites(input.parsedFiles, input.scopes);
+    const canonicalInvokeKeys = input.deferredIndirectSites ?? collectDeferredIndirectSites(input.parsedFiles, input.scopes);
     let unmatchedInvokes = 0;
     for (const parsed of input.parsedFiles) {
         for (const site of parsed.callableFlowSites ?? []) {
@@ -347,7 +367,7 @@ export function emitCallableValueFlow(input) {
         addAddress(bindingKey(fact.filePath, fact.site.destination), bindingKey(fact.filePath, fact.site.source), `address:${fact.filePath}:${fact.site.source.name}`);
     }
     const formalsByGraphId = indexFormalsByGraphId(input.parsedFiles, input.scopes, input.nodeLookup, targetIndexes, aliasesByTargetId);
-    const callSignaturesBySite = indexCallSignatures(input.parsedFiles);
+    const callSignaturesBySite = input.callSignaturesBySite ?? indexCallSignatures(input.parsedFiles);
     const dynamicCallees = new Map();
     const dynamicOverflow = new Set();
     const dynamicTargetHistory = new Map();