gitnexus 1.6.10-rc.21 → 1.6.10-rc.211

package/dist/core/ingestion/di-extractors/types.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The DI resolver contract — the types a per-language/per-framework resolver
+ * implements and the shared `di` pipeline phase consumes.
+ *
+ * A leaf module by design: it imports nothing from this directory, so the
+ * barrel (`./index.ts`, which aggregates the resolver *implementations*) and
+ * each implementation (`./spring.ts`) can both depend on the contract without
+ * depending on each other. The barrel re-exports the two MATCH types, because
+ * consumers of the registry read them off its results; `DiResolver` is not
+ * re-exported, since only implementations need it and they import it from here
+ * directly.
+ *
+ * Mirrors the `import-resolvers/types.ts` split of contract from registry.
+ */
+import type { GraphNode } from '../../../_shared/index.js';
+/** A successful injection-site match, produced by a per-language resolver. */
+export interface DiInjectionMatch {
+    /** The requested dependency type name. */
+    targetTypeName: string;
+    /** A collection receives every matching provider; a single site may need
+     *  framework-specific named/preferred-provider disambiguation. */
+    cardinality: 'single' | 'collection';
+    /** Statically known provider name requested at the injection site. The
+     *  resolver owns the human-readable explanation of that selection. */
+    namedSelection?: {
+        name: string;
+        reason: string;
+        /** Name-first frameworks may fall back to type only for implicit/default
+         * names. Explicit names remain strict. */
+        fallbackToType?: boolean;
+    };
+    /** Most injection edges originate at the owning Class. Factory-method
+     * parameters preserve the Method as the semantic source. */
+    edgeSource?: 'owner-class' | 'site';
+    /** Human-readable edge reason. Framework specifics (names, idioms,
+     *  collection wrapper, gating annotation) live in this payload so the
+     *  shared `di` phase stays framework-neutral. */
+    reason: string;
+}
+/** Provider metadata used by the shared resolver without naming a framework. */
+export interface DiProviderMatch {
+    /** Provider names and aliases that can satisfy a named injection. */
+    names: readonly string[];
+    /** Optional type directly provided by a declaration node, such as a
+     * framework factory method whose node is not itself a Class. */
+    providedTypeName?: string;
+    /** Graph node that declares this provider. The shared phase excludes a
+     * provider from injection into its own declaration site without knowing the
+     * framework-specific declaration model. */
+    declaredByNodeId?: string;
+    /** Present when the framework marks this as its preferred candidate. The
+     *  value is appended to the emitted edge reason when it disambiguates. */
+    preferenceReason?: string;
+}
+/** Per-language DI behavior. Matchers receive whole nodes so the shared phase
+ * remains ignorant of language/framework-specific property shapes. */
+export interface DiResolver {
+    matchInjectionSites(node: GraphNode): readonly DiInjectionMatch[];
+    matchProvider(node: GraphNode): DiProviderMatch | null;
+}

package/dist/core/ingestion/di-extractors/types.js

@@ -0,0 +1,15 @@
+/**
+ * The DI resolver contract — the types a per-language/per-framework resolver
+ * implements and the shared `di` pipeline phase consumes.
+ *
+ * A leaf module by design: it imports nothing from this directory, so the
+ * barrel (`./index.ts`, which aggregates the resolver *implementations*) and
+ * each implementation (`./spring.ts`) can both depend on the contract without
+ * depending on each other. The barrel re-exports the two MATCH types, because
+ * consumers of the registry read them off its results; `DiResolver` is not
+ * re-exported, since only implementations need it and they import it from here
+ * directly.
+ *
+ * Mirrors the `import-resolvers/types.ts` split of contract from registry.
+ */
+export {};

package/dist/core/ingestion/emit-references.js

@@ -224,6 +224,10 @@ function mapKindToType(kind) {
         case 'type-reference':
         case 'import-use':
         case 'macro':
+        // value-ref: function registered as an object-literal property value —
+        // a reference, not an invocation; CALLS are synthesized separately by
+        // the property-dispatch pass (#2437).
+        case 'value-ref':
             return 'USES';
     }
 }

package/dist/core/ingestion/filesystem-walker.js

@@ -4,6 +4,7 @@ import fs from 'fs/promises';
 import path from 'path';
 import { glob } from 'glob';
 import { createIgnoreFilter } from '../../config/ignore-service.js';
+import { mapConcurrent } from '../../lib/utils.js';
 import { logger } from '../logger.js';
 const READ_CONCURRENCY = 32;
 const ANALYZE_PROGRESS_ACTIVE_ENV = 'GITNEXUS_ANALYZE_PROGRESS_ACTIVE';
@@ -60,6 +61,10 @@ export const walkRepositoryPaths = async (repoPath, onProgress) => {
             }
         }
     }
+    // Filesystem/glob traversal order is not stable across filesystems or repeated
+    // scans. Canonicalize once at the scan boundary so every downstream phase sees
+    // the same repository order.
+    entries.sort((left, right) => (left.path < right.path ? -1 : left.path > right.path ? 1 : 0));
     if (skippedLarge > 0) {
         const isDefault = maxFileSizeBytes === DEFAULT_MAX_FILE_SIZE_BYTES;
         const isOverrideUnset = !process.env.GITNEXUS_MAX_FILE_SIZE;
@@ -96,18 +101,17 @@ export const walkRepositoryPaths = async (repoPath, onProgress) => {
  */
 export const readFileContents = async (repoPath, relativePaths) => {
     const contents = new Map();
-    for (let start = 0; start < relativePaths.length; start += READ_CONCURRENCY) {
-        const batch = relativePaths.slice(start, start + READ_CONCURRENCY);
-        const results = await Promise.allSettled(batch.map(async (relativePath) => {
-            const fullPath = path.join(repoPath, relativePath);
-            const content = await fs.readFile(fullPath, 'utf-8');
-            return { path: relativePath, content };
-        }));
-        for (const result of results) {
-            if (result.status === 'fulfilled') {
-                contents.set(result.value.path, result.value.content);
-            }
-        }
+    const results = await mapConcurrent(relativePaths, async (relativePath) => {
+        const fullPath = path.join(repoPath, relativePath);
+        const content = await fs.readFile(fullPath, 'utf-8');
+        return { path: relativePath, content };
+    }, { concurrency: READ_CONCURRENCY });
+    // An unreadable file yields `undefined` (mapConcurrent's per-item degrade) and
+    // is skipped, exactly as the previous allSettled/`status === 'fulfilled'` shape
+    // did — no `onError`, so the skip stays silent per this function's contract.
+    for (const result of results) {
+        if (result)
+            contents.set(result.path, result.content);
     }
     return contents;
 };

package/dist/core/ingestion/finalize-orchestrator.js

@@ -148,6 +148,7 @@ function collectReferenceSites(parsedFiles) {
 function withDefaultHooks(partial) {
     return {
         resolveImportTarget: partial.resolveImportTarget ?? (() => null),
+        isNamespaceImport: partial.isNamespaceImport,
         expandsWildcardTo: partial.expandsWildcardTo ?? (() => []),
         mergeBindings: partial.mergeBindings ??
             ((existing, incoming) => [...existing, ...incoming]),

package/dist/core/ingestion/frameworks/spring/analysis-features.d.ts

@@ -0,0 +1,9 @@
+import type { AnalysisFeatureDescriptor } from '../../../analysis-features.js';
+/** Durable completeness contract for Java/Kotlin Spring Bean evidence. */
+export declare const SPRING_BEAN_INVENTORY_FEATURE: AnalysisFeatureDescriptor;
+/** Durable completeness contract for conditional and auto-configuration evidence. */
+export declare const SPRING_CONDITIONALS_FEATURE: AnalysisFeatureDescriptor;
+/** Durable completeness contract for Spring proxy/advice evidence (#2416). */
+export declare const SPRING_AOP_FEATURE: AnalysisFeatureDescriptor;
+/** Durable completeness contract for scheduled, event, messaging, and job entry points (#2417). */
+export declare const SPRING_NON_HTTP_HANDLERS_FEATURE: AnalysisFeatureDescriptor;

package/dist/core/ingestion/frameworks/spring/analysis-features.js

@@ -0,0 +1,41 @@
+import { isSpringBeanCandidateSourceFile } from './bean-catalog.js';
+/** Durable completeness contract for Java/Kotlin Spring Bean evidence. */
+export const SPRING_BEAN_INVENTORY_FEATURE = {
+    id: 'spring.bean-inventory',
+    version: 2,
+    appliesTo: (filePaths) => filePaths.some(isSpringBeanCandidateSourceFile),
+};
+function isSpringConditionOrAutoConfigurationFile(filePath) {
+    const normalized = `/${filePath.replaceAll('\\', '/')}`.toLowerCase();
+    return (normalized.endsWith('.java') ||
+        normalized.endsWith('.kt') ||
+        normalized.endsWith('.kts') ||
+        normalized.endsWith('/meta-inf/spring.factories') ||
+        normalized.endsWith('/meta-inf/spring/org.springframework.boot.autoconfigure.autoconfiguration.imports'));
+}
+/** Durable completeness contract for conditional and auto-configuration evidence. */
+export const SPRING_CONDITIONALS_FEATURE = {
+    id: 'spring.conditionals-auto-configuration',
+    version: 1,
+    appliesTo: (filePaths) => filePaths.some(isSpringConditionOrAutoConfigurationFile),
+};
+/**
+ * Candidate-language approximation, not a claim that the file contains AOP.
+ * Kotlin scripts are included because `.kts` is a supported Kotlin input.
+ */
+function isJvmSourceFile(filePath) {
+    const normalized = filePath.replaceAll('\\', '/').toLowerCase();
+    return normalized.endsWith('.java') || normalized.endsWith('.kt') || normalized.endsWith('.kts');
+}
+/** Durable completeness contract for Spring proxy/advice evidence (#2416). */
+export const SPRING_AOP_FEATURE = {
+    id: 'spring.aop-advice',
+    version: 1,
+    appliesTo: (filePaths) => filePaths.some(isJvmSourceFile),
+};
+/** Durable completeness contract for scheduled, event, messaging, and job entry points (#2417). */
+export const SPRING_NON_HTTP_HANDLERS_FEATURE = {
+    id: 'spring.non-http-handlers',
+    version: 1,
+    appliesTo: (filePaths) => filePaths.some(isJvmSourceFile),
+};

package/dist/core/ingestion/frameworks/spring/annotation-arguments.d.ts

@@ -0,0 +1,13 @@
+export interface SpringAnnotationArgument {
+    readonly name?: string;
+    readonly value: string;
+}
+/** Parse Java/Kotlin annotation arguments without evaluating constants. */
+export declare function parseSpringAnnotationArguments(annotationText: string): readonly SpringAnnotationArgument[] | null;
+export declare function parseStaticStringLiteral(value: string): string | null;
+/** Parse one string literal or a Java/Kotlin annotation string array. */
+export declare function parseStaticStringValues(value: string): readonly string[] | null;
+/** Parse `Foo.class` or `Foo::class`; an Object/Any default returns an empty string. */
+export declare function parseStaticClassLiteral(value: string): string | null;
+/** Normalize a declared bean type to the graph's simple/qualified raw type key. */
+export declare function normalizeSpringBeanType(rawType: string): string | null;

package/dist/core/ingestion/frameworks/spring/annotation-arguments.js

@@ -0,0 +1,227 @@
+function splitTopLevel(value, separator) {
+    const parts = [];
+    const stack = [];
+    let quote = null;
+    let escaped = false;
+    let start = 0;
+    // Angle brackets are deliberate: Java/Kotlin generic expressions may contain
+    // commas that are not annotation-argument separators. Ambiguous comparison
+    // expressions remain unsupported and fail closed instead of being mis-split.
+    const closing = new Map([
+        ['(', ')'],
+        ['[', ']'],
+        ['{', '}'],
+        ['<', '>'],
+    ]);
+    for (let index = 0; index < value.length; index++) {
+        const char = value[index];
+        if (quote === '"""') {
+            if (value.startsWith('"""', index)) {
+                quote = null;
+                index += 2;
+            }
+            continue;
+        }
+        if (quote !== null) {
+            if (escaped)
+                escaped = false;
+            else if (char === '\\')
+                escaped = true;
+            else if (char === quote)
+                quote = null;
+            continue;
+        }
+        if (value.startsWith('"""', index)) {
+            quote = '"""';
+            index += 2;
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            continue;
+        }
+        const closingChar = closing.get(char);
+        if (closingChar !== undefined) {
+            stack.push(closingChar);
+            continue;
+        }
+        if (stack[stack.length - 1] === char) {
+            stack.pop();
+            continue;
+        }
+        if (char === separator && stack.length === 0) {
+            parts.push(value.slice(start, index).trim());
+            start = index + 1;
+        }
+    }
+    if (quote !== null || stack.length > 0)
+        return null;
+    parts.push(value.slice(start).trim());
+    return parts;
+}
+function topLevelAssignment(argument) {
+    const stack = [];
+    let quote = null;
+    let escaped = false;
+    // Keep the same deliberate generic-delimiter policy as splitTopLevel.
+    const closing = new Map([
+        ['(', ')'],
+        ['[', ']'],
+        ['{', '}'],
+        ['<', '>'],
+    ]);
+    for (let index = 0; index < argument.length; index++) {
+        const char = argument[index];
+        if (quote === '"""') {
+            if (argument.startsWith('"""', index)) {
+                quote = null;
+                index += 2;
+            }
+            continue;
+        }
+        if (quote !== null) {
+            if (escaped)
+                escaped = false;
+            else if (char === '\\')
+                escaped = true;
+            else if (char === quote)
+                quote = null;
+            continue;
+        }
+        if (argument.startsWith('"""', index)) {
+            quote = '"""';
+            index += 2;
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            continue;
+        }
+        const closingChar = closing.get(char);
+        if (closingChar !== undefined) {
+            stack.push(closingChar);
+            continue;
+        }
+        if (stack[stack.length - 1] === char) {
+            stack.pop();
+            continue;
+        }
+        if (char === '=' && stack.length === 0)
+            return index;
+    }
+    return -1;
+}
+/** Parse Java/Kotlin annotation arguments without evaluating constants. */
+export function parseSpringAnnotationArguments(annotationText) {
+    const open = annotationText.indexOf('(');
+    if (open === -1)
+        return [];
+    const close = annotationText.lastIndexOf(')');
+    if (close < open || annotationText.slice(close + 1).trim().length > 0)
+        return null;
+    const body = annotationText.slice(open + 1, close).trim();
+    if (body.length === 0)
+        return [];
+    const rawArguments = splitTopLevel(body, ',');
+    if (rawArguments === null || rawArguments.some((argument) => argument.length === 0))
+        return null;
+    const parsed = [];
+    for (const raw of rawArguments) {
+        const assignment = topLevelAssignment(raw);
+        if (assignment === -1) {
+            parsed.push({ value: raw });
+            continue;
+        }
+        const name = raw.slice(0, assignment).trim();
+        const value = raw.slice(assignment + 1).trim();
+        if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) || value.length === 0)
+            return null;
+        parsed.push({ name, value });
+    }
+    return parsed;
+}
+export function parseStaticStringLiteral(value) {
+    const trimmed = value.trim();
+    if (trimmed.startsWith('"""')) {
+        if (trimmed.length < 6 || !trimmed.endsWith('"""'))
+            return null;
+        const raw = trimmed.slice(3, -3);
+        if (raw.includes('"""') || /\$(?:\{|[A-Za-z_])/.test(raw))
+            return null;
+        return raw;
+    }
+    const match = /^"((?:\\.|[^"\\])*)"$/s.exec(trimmed);
+    if (match === null)
+        return null;
+    if (/(^|[^\\])\$(?:\{|[A-Za-z_])/.test(match[1]))
+        return null;
+    try {
+        return JSON.parse(`"${match[1]}"`);
+    }
+    catch {
+        return null;
+    }
+}
+/** Parse one string literal or a Java/Kotlin annotation string array. */
+export function parseStaticStringValues(value) {
+    const trimmed = value.trim();
+    const pair = (trimmed.startsWith('{') && trimmed.endsWith('}')) ||
+        (trimmed.startsWith('[') && trimmed.endsWith(']'));
+    const body = pair ? trimmed.slice(1, -1).trim() : trimmed;
+    if (body.length === 0)
+        return [];
+    const parts = pair ? splitTopLevel(body, ',') : [body];
+    if (parts === null)
+        return null;
+    const strings = [];
+    for (const part of parts) {
+        const parsed = parseStaticStringLiteral(part);
+        if (parsed === null)
+            return null;
+        strings.push(parsed);
+    }
+    return strings;
+}
+/** Parse `Foo.class` or `Foo::class`; an Object/Any default returns an empty string. */
+export function parseStaticClassLiteral(value) {
+    const compact = value.replace(/\s+/g, '');
+    const match = /^([A-Za-z_$][A-Za-z0-9_$.]*)(?:\.class|::class)$/.exec(compact);
+    if (match === null)
+        return null;
+    const typeName = match[1];
+    if (typeName === 'Object' ||
+        typeName === 'java.lang.Object' ||
+        typeName === 'Any' ||
+        typeName === 'kotlin.Any') {
+        return '';
+    }
+    return typeName;
+}
+/** Normalize a declared bean type to the graph's simple/qualified raw type key. */
+export function normalizeSpringBeanType(rawType) {
+    // Projection keywords are tokens only when separated from the following
+    // type. Strip them before whitespace compaction so valid lowercase type
+    // aliases such as `outputStream` and `inside.Type` remain intact.
+    let normalized = rawType
+        .replace(/^(?:out|in)\s+/, '')
+        .replace(/([<,])\s*(?:out|in)\s+/g, '$1')
+        .replace(/\s+/g, '')
+        .replace(/^kotlin\.collections\.Mutable(List|Set|Collection|Map)(?=<|$)/, 'kotlin.collections.$1')
+        .replace(/^Mutable(List|Set|Collection|Map)(?=<|$)/, '$1')
+        .replace(/\?$/, '');
+    const generic = normalized.indexOf('<');
+    if (generic !== -1) {
+        if (!normalized.endsWith('>'))
+            return null;
+        normalized = normalized.slice(0, generic);
+    }
+    if (normalized === 'void' ||
+        normalized === 'Void' ||
+        normalized === 'Unit' ||
+        normalized === 'kotlin.Unit') {
+        return null;
+    }
+    return /^[A-Za-z_$][A-Za-z0-9_$]*(?:\.[A-Za-z_$][A-Za-z0-9_$]*)*$/.test(normalized)
+        ? normalized
+        : null;
+}

package/dist/core/ingestion/frameworks/spring/aop-candidates.d.ts

@@ -0,0 +1,15 @@
+import type { GraphNode } from '../../../../_shared/index.js';
+import type { SpringAopStaticPointcut } from './aop.js';
+export interface SpringAopOwnedMethod {
+    readonly method: GraphNode;
+    readonly owner: GraphNode;
+}
+export interface SpringAopCandidateIndex {
+    readonly totalCandidates: number;
+    candidatesFor(pointcut: SpringAopStaticPointcut): readonly SpringAopOwnedMethod[];
+}
+/**
+ * Build immutable candidate lists once per pipeline run. The pointcut matcher
+ * remains the final authority; this index only returns safe supersets.
+ */
+export declare function createSpringAopCandidateIndex(candidates: readonly SpringAopOwnedMethod[], methodAnnotations: ReadonlyMap<string, ReadonlySet<string>>): SpringAopCandidateIndex;

package/dist/core/ingestion/frameworks/spring/aop-candidates.js

@@ -0,0 +1,85 @@
+function ownerPatternLiteralPrefix(pattern) {
+    const wildcardIndex = pattern.indexOf('*');
+    const descendantIndex = pattern.indexOf('..');
+    const firstDynamicIndex = [wildcardIndex, descendantIndex]
+        .filter((index) => index >= 0)
+        .reduce((first, index) => Math.min(first, index), pattern.length);
+    return pattern.slice(0, firstDynamicIndex);
+}
+function lowerBoundByQualifiedName(buckets, prefix) {
+    let low = 0;
+    let high = buckets.length;
+    while (low < high) {
+        const middle = low + Math.floor((high - low) / 2);
+        if ((buckets[middle]?.qualifiedName ?? '') < prefix)
+            low = middle + 1;
+        else
+            high = middle;
+    }
+    return low;
+}
+function compareStrings(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+/**
+ * Build immutable candidate lists once per pipeline run. The pointcut matcher
+ * remains the final authority; this index only returns safe supersets.
+ */
+export function createSpringAopCandidateIndex(candidates, methodAnnotations) {
+    const allCandidates = [...candidates];
+    const candidatesByAnnotation = new Map();
+    const candidatesByExactOwner = new Map();
+    const ownerBucketsById = new Map();
+    for (const candidate of allCandidates) {
+        for (const annotation of methodAnnotations.get(candidate.method.id) ?? []) {
+            const annotated = candidatesByAnnotation.get(annotation) ?? [];
+            annotated.push(candidate);
+            candidatesByAnnotation.set(annotation, annotated);
+        }
+        const qualifiedName = candidate.owner.properties.qualifiedName;
+        if (typeof qualifiedName !== 'string' || qualifiedName.length === 0)
+            continue;
+        const exactOwnerCandidates = candidatesByExactOwner.get(qualifiedName) ?? [];
+        exactOwnerCandidates.push(candidate);
+        candidatesByExactOwner.set(qualifiedName, exactOwnerCandidates);
+        let bucket = ownerBucketsById.get(candidate.owner.id);
+        if (bucket === undefined) {
+            bucket = { id: candidate.owner.id, qualifiedName, candidates: [] };
+            ownerBucketsById.set(candidate.owner.id, bucket);
+        }
+        bucket.candidates.push(candidate);
+    }
+    const ownerBuckets = [...ownerBucketsById.values()].sort((left, right) => compareStrings(left.qualifiedName, right.qualifiedName) || compareStrings(left.id, right.id));
+    const candidatesByOwnerPattern = new Map();
+    return {
+        totalCandidates: allCandidates.length,
+        candidatesFor(pointcut) {
+            if (pointcut.kind === 'annotation') {
+                return candidatesByAnnotation.get(pointcut.annotation) ?? [];
+            }
+            if (!pointcut.ownerPattern.includes('*') && !pointcut.ownerPattern.includes('..')) {
+                return candidatesByExactOwner.get(pointcut.ownerPattern) ?? [];
+            }
+            // Unqualified wildcard patterns (for example `*Service` or `Order*`)
+            // match the owner simple name. The qualified-name prefix index cannot
+            // safely narrow those, so preserve the full candidate superset.
+            if (!pointcut.ownerPattern.includes('.'))
+                return allCandidates;
+            const prefix = ownerPatternLiteralPrefix(pointcut.ownerPattern);
+            if (prefix.length === 0)
+                return allCandidates;
+            const cached = candidatesByOwnerPattern.get(pointcut.ownerPattern);
+            if (cached !== undefined)
+                return cached;
+            const selected = [];
+            for (let index = lowerBoundByQualifiedName(ownerBuckets, prefix); index < ownerBuckets.length; index += 1) {
+                const bucket = ownerBuckets[index];
+                if (bucket === undefined || !bucket.qualifiedName.startsWith(prefix))
+                    break;
+                selected.push(...bucket.candidates);
+            }
+            candidatesByOwnerPattern.set(pointcut.ownerPattern, selected);
+            return selected;
+        },
+    };
+}

package/dist/core/ingestion/frameworks/spring/aop.d.ts

@@ -0,0 +1,118 @@
+import type { GraphNode, ParsedFile, Range, ScopeId } from '../../../../_shared/index.js';
+import type { KnowledgeGraph } from '../../../graph/types.js';
+import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js';
+import type { GraphNodeLookup } from '../../scope-resolution/graph-bridge/node-lookup.js';
+export declare const SPRING_AOP_REASON_PREFIX = "spring-aop:v1:";
+export declare const SPRING_AOP_EVIDENCE_DESCRIPTION_PREFIX = "Spring AOP: ";
+export declare const SPRING_AOP_EVIDENCE_ID_PREFIX = "CodeElement:spring-aop:";
+export type SpringAopBehavior = 'transactional' | 'caching' | 'cacheable' | 'cache-evict' | 'cache-put' | 'authorization';
+export type SpringAopAdviceKind = 'around' | 'before' | 'after' | 'after-returning' | 'after-throwing' | 'pointcut';
+export interface SpringAopAnnotationFact {
+    readonly name: string;
+    readonly text: string;
+    readonly line: number;
+    /** Kotlin use-site targets do not describe a callable annotation here. */
+    readonly useSiteTarget?: string;
+}
+export interface SpringAopOwnerFact<Annotation extends SpringAopAnnotationFact = SpringAopAnnotationFact> {
+    readonly ownerScopeId: ScopeId;
+    readonly ownerKind: 'class' | 'callable';
+    readonly ownerFilePath?: string;
+    /** Exact syntax range used only as a fail-closed bridge for collapsed language scopes. */
+    readonly ownerRange?: Range;
+    /** The language models this owner/member as static, but it belongs to a singleton instance. */
+    readonly singletonInstance?: true;
+    readonly annotations: readonly Annotation[];
+}
+export interface SpringAopMetadataAdapter<Annotation extends SpringAopAnnotationFact> {
+    getFacts(filePath: string): readonly SpringAopOwnerFact<Annotation>[];
+    isPackageVisibilityIncomplete(filePath: string): boolean;
+}
+export interface SpringAopBehaviorReason {
+    readonly kind: 'behavior';
+    readonly annotation: string;
+    readonly behavior: SpringAopBehavior;
+    readonly declaredOn: 'class' | 'method';
+    readonly activation: 'unknown';
+    readonly proxy: 'possible';
+}
+export interface SpringAopAdviceReason {
+    readonly kind: 'advice';
+    readonly annotation: string;
+    readonly advice: Exclude<SpringAopAdviceKind, 'pointcut'>;
+    readonly pointcut: string;
+    readonly match: 'static';
+    readonly activation: 'unknown';
+    readonly proxy: 'possible';
+}
+export interface SpringAopPointcutReason {
+    readonly kind: 'pointcut';
+    readonly annotation: string;
+    readonly pointcut: string | null;
+    readonly match: 'static' | 'unresolved';
+    readonly resolution: 'resolved' | 'unknown';
+}
+export interface SpringAopAspectReason {
+    readonly kind: 'aspect';
+    readonly annotation: string;
+    readonly activation: 'unknown';
+    readonly registration: 'unknown';
+}
+export type SpringAopReason = SpringAopBehaviorReason | SpringAopAdviceReason | SpringAopPointcutReason | SpringAopAspectReason;
+export interface SpringAopAspectRecord {
+    readonly ownerId: string;
+    readonly annotation: string;
+    readonly line: number;
+}
+export interface SpringAopBehaviorRecord {
+    readonly ownerId: string;
+    readonly ownerKind: 'class' | 'callable';
+    readonly annotation: string;
+    readonly behavior: SpringAopBehavior;
+    readonly line: number;
+}
+export interface SpringAopAdviceRecord {
+    readonly ownerId: string;
+    readonly annotation: string;
+    readonly advice: SpringAopAdviceKind;
+    readonly pointcut: string | null;
+    readonly line: number;
+}
+export interface SpringAopGraphMetadata {
+    readonly candidateFilePaths: ReadonlySet<string>;
+    readonly aspectClassIds: ReadonlySet<string>;
+    readonly singletonInstanceClassIds: ReadonlySet<string>;
+    readonly aspects: readonly SpringAopAspectRecord[];
+    readonly behaviors: readonly SpringAopBehaviorRecord[];
+    readonly advices: readonly SpringAopAdviceRecord[];
+}
+export declare function getSpringAopGraphMetadata(graph: KnowledgeGraph): SpringAopGraphMetadata;
+export declare function hasSpringAopRelevantAnnotation(annotations: readonly Pick<SpringAopAnnotationFact, 'name'>[]): boolean;
+/**
+ * Resolve syntax facts after imports and package visibility are complete.
+ * Language adapters own AST shape only; this shared layer owns framework FQNs.
+ */
+export declare function createSpringAopMetadataAttacher<Annotation extends SpringAopAnnotationFact>(adapter: SpringAopMetadataAdapter<Annotation>): (graph: KnowledgeGraph, parsedFiles: readonly ParsedFile[], nodeLookup: GraphNodeLookup, indexes: ScopeResolutionIndexes) => void;
+export declare function encodeSpringAopReason(reason: SpringAopReason): string;
+/** Decode only the current, validated reason contract; malformed/foreign rows fail closed. */
+export declare function decodeSpringAopReason(value: unknown): SpringAopReason | undefined;
+export declare function isSpringAopEvidenceNode(node: GraphNode): boolean;
+export interface SpringAopExecutionPointcut {
+    readonly kind: 'execution';
+    readonly ownerPattern: string;
+    readonly methodPattern: string;
+    readonly visibility?: 'public';
+    readonly parameterCount?: number;
+}
+export interface SpringAopWithinPointcut {
+    readonly kind: 'within';
+    readonly ownerPattern: string;
+}
+export interface SpringAopAnnotationPointcut {
+    readonly kind: 'annotation';
+    readonly annotation: string;
+}
+export type SpringAopStaticPointcut = SpringAopExecutionPointcut | SpringAopWithinPointcut | SpringAopAnnotationPointcut;
+/** Parse the deliberately narrow, fully static pointcut subset supported in v1. */
+export declare function parseSpringAopPointcut(expression: string): SpringAopStaticPointcut | null;
+export declare function springAopPointcutMatches(pointcut: SpringAopStaticPointcut, owner: GraphNode, method: GraphNode, methodAnnotations?: ReadonlySet<string>): boolean;