gitnexus 1.6.10-rc.99 → 1.6.10

package/dist/lib/utils.d.ts

@@ -1 +1,114 @@
 export declare const generateId: (label: string, name: string) => string;
+/**
+ * Total order on strings by UTF-16 code unit — deliberately NOT `localeCompare`.
+ *
+ * `localeCompare` resolves against the host's default ICU locale, so two machines
+ * can order the same pair differently and a tie-broken cap keeps a different
+ * subset on each (#2787). Code-unit order is host-independent and matches the
+ * binary `ORDER BY` the graph queries use, so a JS re-sort reproduces the DB's
+ * order instead of fighting it.
+ *
+ * Use this for every tiebreak that feeds a `.slice()`, a page boundary, or any
+ * other cut — `Array.prototype.sort` is stable, so a comparator that returns 0
+ * for distinct elements silently falls back to input order.
+ */
+export declare const compareCodeUnits: (a: string, b: string) => number;
+/**
+ * How many links of an `Error.cause` chain any walker below visits, counting
+ * the head. THE bound — hand-rolled copies had drifted to three different
+ * numbers with three different loop conditions (`depth < 5` in two places,
+ * `depth <= 5` in a third, i.e. six levels).
+ *
+ * The bound exists purely so a cyclic chain (`a.cause = b; b.cause = a`)
+ * cannot loop forever. Real chains are one or two links deep — the ingestion
+ * phase runner wraps a phase failure once as
+ * `new Error("Phase 'X' failed: …", { cause })` — so five leaves ample
+ * headroom for future nesting.
+ */
+export declare const CAUSE_CHAIN_MAX_DEPTH = 5;
+/**
+ * Walk `err` and its `cause` chain, head first, yielding each `Error` link.
+ *
+ * Stops at the first non-`Error` link (a `cause` may legally be any value, and
+ * a non-Error carries no further `cause` worth following) and after
+ * `maxDepth` links. Non-`Error` input yields nothing.
+ *
+ * THE single cause-chain traversal. Consume this (or {@link findInCauseChain})
+ * rather than re-rolling the `for (let depth = 0; …; current = current.cause)`
+ * loop: every hand-rolled copy has to re-decide the bound and the loop
+ * condition, and they did not agree.
+ */
+export declare function causeChain(err: unknown, maxDepth?: number): Generator<Error>;
+/**
+ * Find the first link of `err`'s cause chain that `match` accepts.
+ *
+ * Load-bearing for CLI error classification: the ingestion phase runner
+ * rewraps every phase failure as `new Error("Phase 'X' failed: …", { cause })`,
+ * so a bare `instanceof` at the CLI boundary misses the real error entirely
+ * and falls through to a generic stack dump. Classify by TYPE through this
+ * helper (the repo norm from #2385), never by message text.
+ */
+export declare function findInCauseChain<T>(err: unknown, match: (e: unknown) => e is T, maxDepth?: number): T | undefined;
+/**
+ * Drop a Windows extended-length (`\\?\`) prefix from a path (#2667).
+ *
+ * **Comparison domain only.** Never apply this to a string that is about to be
+ * handed to `fs`: libuv's `fs__capture_path` only converts WTF-8 to UTF-16 and
+ * does *not* re-add the prefix for over-MAX_PATH paths, so stripping an
+ * filesystem-facing path would break long-path access on hosts that have not
+ * opted into `LongPathsEnabled`. Registry keys, repo-resolution lookups and
+ * other pure string comparisons are safe — and are exactly where an
+ * un-normalized prefix silently fails to match.
+ *
+ * The prefix can only ever arrive from caller-supplied input (`path.resolve`
+ * preserves it); `realpathSync.native` cannot emit it, because libuv's
+ * `fs__realpath_handle` strips it unconditionally.
+ *
+ * `\\?\Volume{GUID}\…` is deliberately left alone: the remainder of a volume-GUID
+ * path is not a usable path, so stripping it would invent a wrong one. The `\\.\`
+ * device namespace is left alone for the same reason and one more — most of what
+ * it addresses (`\\.\PhysicalDrive0`, `\\.\COM1`, `\\.\pipe\…`) is not a
+ * filesystem path at all. Both forms simply fail to match a registry entry, which
+ * is the safe direction. `platform` is explicit so the transform is unit-testable
+ * off Windows — same shape as `normalizeAnalyzerRootPath` in
+ * `src/core/analyzer-identity.ts`.
+ *
+ * Call this on a `path.resolve`d path. Only the backslash spelling is matched,
+ * which is sufficient there because `path.win32.resolve` already folds the
+ * forward-slash spelling into it (`//?/D:/a` → `\\?\D:\a`). A raw, unresolved
+ * `//?/…` string is returned unchanged rather than half-normalized.
+ */
+export declare const stripWindowsLongPathPrefix: (p: string, platform?: NodeJS.Platform) => string;
+/**
+ * Split `items` into consecutive slices of at most `size`.
+ *
+ * Returns an empty array for empty input, and never returns an empty slice, so
+ * `for (const batch of chunk(xs, n))` always has something to work on.
+ *
+ * Callers batching a GRAPH QUERY should take the size from `core/lbug/query-batch.ts`,
+ * which documents why a query built from a caller-sized array needs a ceiling at
+ * all (#2915) and which of the two ceilings applies: `LBUG_QUERY_BATCH_SIZE` when
+ * each item makes the query do more work, `LBUG_ID_PROBE_BATCH_SIZE` when it is a
+ * plain `id IN $ids` probe and round trips dominate. They differ by 10x, in
+ * opposite directions, for that reason.
+ */
+export declare function chunk<T>(items: readonly T[], size: number): T[][];
+/**
+ * Run `run` over each item with at most `concurrency` in flight, returning the
+ * results in input order.
+ *
+ * A failure is reported through `onError` and yields `undefined` for that item,
+ * so one bad item degrades the result (the caller raises its own `partial`
+ * flag) instead of discarding the items that succeeded beside it.
+ *
+ * This SCHEDULES, it does not synchronize: `run` must be safe to execute
+ * concurrently with itself. Both kinds of caller here are — `fs.readFile` per
+ * path in the ingestion walkers, and graph queries, where `executeParameterized`
+ * checks a connection out of the per-repo pool for the duration of the query
+ * (`pool-adapter.ts`) so parallel calls never share one. The default leaves
+ * headroom for other in-flight work.
+ */
+export declare function mapConcurrent<T, R>(items: readonly T[], run: (item: T) => Promise<R>, options?: {
+    concurrency?: number;
+    onError?: (error: unknown) => void;
+}): Promise<(R | undefined)[]>;

package/dist/lib/utils.js

@@ -1,3 +1,188 @@
 export const generateId = (label, name) => {
     return `${label}:${name}`;
 };
+/**
+ * Total order on strings by UTF-16 code unit — deliberately NOT `localeCompare`.
+ *
+ * `localeCompare` resolves against the host's default ICU locale, so two machines
+ * can order the same pair differently and a tie-broken cap keeps a different
+ * subset on each (#2787). Code-unit order is host-independent and matches the
+ * binary `ORDER BY` the graph queries use, so a JS re-sort reproduces the DB's
+ * order instead of fighting it.
+ *
+ * Use this for every tiebreak that feeds a `.slice()`, a page boundary, or any
+ * other cut — `Array.prototype.sort` is stable, so a comparator that returns 0
+ * for distinct elements silently falls back to input order.
+ */
+export const compareCodeUnits = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+/**
+ * How many links of an `Error.cause` chain any walker below visits, counting
+ * the head. THE bound — hand-rolled copies had drifted to three different
+ * numbers with three different loop conditions (`depth < 5` in two places,
+ * `depth <= 5` in a third, i.e. six levels).
+ *
+ * The bound exists purely so a cyclic chain (`a.cause = b; b.cause = a`)
+ * cannot loop forever. Real chains are one or two links deep — the ingestion
+ * phase runner wraps a phase failure once as
+ * `new Error("Phase 'X' failed: …", { cause })` — so five leaves ample
+ * headroom for future nesting.
+ */
+export const CAUSE_CHAIN_MAX_DEPTH = 5;
+/**
+ * Walk `err` and its `cause` chain, head first, yielding each `Error` link.
+ *
+ * Stops at the first non-`Error` link (a `cause` may legally be any value, and
+ * a non-Error carries no further `cause` worth following) and after
+ * `maxDepth` links. Non-`Error` input yields nothing.
+ *
+ * THE single cause-chain traversal. Consume this (or {@link findInCauseChain})
+ * rather than re-rolling the `for (let depth = 0; …; current = current.cause)`
+ * loop: every hand-rolled copy has to re-decide the bound and the loop
+ * condition, and they did not agree.
+ */
+export function* causeChain(err, maxDepth = CAUSE_CHAIN_MAX_DEPTH) {
+    let current = err;
+    for (let depth = 0; depth < maxDepth && current instanceof Error; depth++) {
+        yield current;
+        current = current.cause;
+    }
+}
+/**
+ * Find the first link of `err`'s cause chain that `match` accepts.
+ *
+ * Load-bearing for CLI error classification: the ingestion phase runner
+ * rewraps every phase failure as `new Error("Phase 'X' failed: …", { cause })`,
+ * so a bare `instanceof` at the CLI boundary misses the real error entirely
+ * and falls through to a generic stack dump. Classify by TYPE through this
+ * helper (the repo norm from #2385), never by message text.
+ */
+export function findInCauseChain(err, match, maxDepth = CAUSE_CHAIN_MAX_DEPTH) {
+    for (const link of causeChain(err, maxDepth)) {
+        if (match(link))
+            return link;
+    }
+    return undefined;
+}
+/**
+ * Drop a Windows extended-length (`\\?\`) prefix from a path (#2667).
+ *
+ * **Comparison domain only.** Never apply this to a string that is about to be
+ * handed to `fs`: libuv's `fs__capture_path` only converts WTF-8 to UTF-16 and
+ * does *not* re-add the prefix for over-MAX_PATH paths, so stripping an
+ * filesystem-facing path would break long-path access on hosts that have not
+ * opted into `LongPathsEnabled`. Registry keys, repo-resolution lookups and
+ * other pure string comparisons are safe — and are exactly where an
+ * un-normalized prefix silently fails to match.
+ *
+ * The prefix can only ever arrive from caller-supplied input (`path.resolve`
+ * preserves it); `realpathSync.native` cannot emit it, because libuv's
+ * `fs__realpath_handle` strips it unconditionally.
+ *
+ * `\\?\Volume{GUID}\…` is deliberately left alone: the remainder of a volume-GUID
+ * path is not a usable path, so stripping it would invent a wrong one. The `\\.\`
+ * device namespace is left alone for the same reason and one more — most of what
+ * it addresses (`\\.\PhysicalDrive0`, `\\.\COM1`, `\\.\pipe\…`) is not a
+ * filesystem path at all. Both forms simply fail to match a registry entry, which
+ * is the safe direction. `platform` is explicit so the transform is unit-testable
+ * off Windows — same shape as `normalizeAnalyzerRootPath` in
+ * `src/core/analyzer-identity.ts`.
+ *
+ * Call this on a `path.resolve`d path. Only the backslash spelling is matched,
+ * which is sufficient there because `path.win32.resolve` already folds the
+ * forward-slash spelling into it (`//?/D:/a` → `\\?\D:\a`). A raw, unresolved
+ * `//?/…` string is returned unchanged rather than half-normalized.
+ */
+export const stripWindowsLongPathPrefix = (p, platform = process.platform) => {
+    if (platform !== 'win32')
+        return p;
+    // Both spellings are case-insensitive: the Windows object namespace that
+    // `\\?\` addresses is, so `\\?\unc\…` is as valid as `\\?\UNC\…`.
+    //
+    // Each pattern requires the component that makes the remainder a usable path —
+    // a share name after `UNC\`, a separator after the drive colon. Without those
+    // the slice would emit something worse than the input it was handed: `\\?\UNC`
+    // would become the bare root `\\`, and the drive-relative `\\?\D:foo` would
+    // become `D:foo`, which is not absolute and would resolve against the process
+    // cwd if a future caller ever passed it to `fs`. A malformed extended path is
+    // left untouched instead, so it simply fails to match a registry entry.
+    if (/^\\\\\?\\UNC\\(?=[^\\])/i.test(p))
+        return `\\\\${p.slice(8)}`;
+    if (/^\\\\\?\\[A-Za-z]:\\/.test(p))
+        return p.slice(4);
+    return p;
+};
+/**
+ * Split `items` into consecutive slices of at most `size`.
+ *
+ * Returns an empty array for empty input, and never returns an empty slice, so
+ * `for (const batch of chunk(xs, n))` always has something to work on.
+ *
+ * Callers batching a GRAPH QUERY should take the size from `core/lbug/query-batch.ts`,
+ * which documents why a query built from a caller-sized array needs a ceiling at
+ * all (#2915) and which of the two ceilings applies: `LBUG_QUERY_BATCH_SIZE` when
+ * each item makes the query do more work, `LBUG_ID_PROBE_BATCH_SIZE` when it is a
+ * plain `id IN $ids` probe and round trips dominate. They differ by 10x, in
+ * opposite directions, for that reason.
+ */
+export function chunk(items, size) {
+    // `NaN` fails every comparison, so a bare `size < 1` lets it through and
+    // A size is a COUNT, so it has to be a positive integer — `Number.isInteger`
+    // rather than `Number.isFinite`, because a fractional size silently DUPLICATES
+    // items rather than failing: `slice` truncates its indices while `i` does not,
+    // so size 1.5 yields slice(0, 1.5) = items 0-1 and then slice(1.5, 3) = items
+    // 1-2, and item 1 lands in two batches. `NaN` is the other shape this rejects —
+    // it fails every comparison, so a bare `size < 1` lets it through and `i += NaN`
+    // produces exactly one empty slice, which the docstring promises never to
+    // return. `mapConcurrent`'s `Math.max(1, …)` propagates a NaN concurrency the
+    // same way.
+    if (!Number.isInteger(size) || size < 1) {
+        throw new RangeError(`chunk size must be a positive integer, got ${size}`);
+    }
+    const batches = [];
+    for (let i = 0; i < items.length; i += size)
+        batches.push(items.slice(i, i + size));
+    return batches;
+}
+/**
+ * Run `run` over each item with at most `concurrency` in flight, returning the
+ * results in input order.
+ *
+ * A failure is reported through `onError` and yields `undefined` for that item,
+ * so one bad item degrades the result (the caller raises its own `partial`
+ * flag) instead of discarding the items that succeeded beside it.
+ *
+ * This SCHEDULES, it does not synchronize: `run` must be safe to execute
+ * concurrently with itself. Both kinds of caller here are — `fs.readFile` per
+ * path in the ingestion walkers, and graph queries, where `executeParameterized`
+ * checks a connection out of the per-repo pool for the duration of the query
+ * (`pool-adapter.ts`) so parallel calls never share one. The default leaves
+ * headroom for other in-flight work.
+ */
+export async function mapConcurrent(items, run, options = {}) {
+    const settle = async (item) => {
+        try {
+            return await run(item);
+        }
+        catch (error) {
+            // Reporting a failure must not become a failure. `onError` is caller-supplied
+            // — a logger with a bad format string is enough — and an uncaught throw here
+            // rejects `settle`, which rejects the whole `Promise.all` wave and discards
+            // the neighbouring successes this function exists to preserve.
+            try {
+                options.onError?.(error);
+            }
+            catch {
+                /* empty */
+            }
+            return undefined;
+        }
+    };
+    // Wave scheduling rather than a rolling window: measured on the real query
+    // path the two are within noise (538ms vs 532ms on a 1,000-file diff, whose
+    // per-batch times spread only 1.35x), and most inputs produce a single wave.
+    const results = [];
+    for (const wave of chunk(items, Math.max(1, options.concurrency ?? 4))) {
+        results.push(...(await Promise.all(wave.map(settle))));
+    }
+    return results;
+}

package/dist/mcp/local/aop-metadata.d.ts

@@ -0,0 +1,77 @@
+import { type SpringAopReason } from '../../core/ingestion/frameworks/spring/aop.js';
+type SpringAopBehaviorReason = Extract<SpringAopReason, {
+    kind: 'behavior';
+}>;
+type SpringAopAdviceReason = Extract<SpringAopReason, {
+    kind: 'advice';
+}>;
+type SpringAopAspectReason = Extract<SpringAopReason, {
+    kind: 'aspect';
+}>;
+type SpringAopPointcutReason = Extract<SpringAopReason, {
+    kind: 'pointcut';
+}>;
+export interface SpringAopBehaviorMetadata {
+    readonly annotation: string;
+    readonly behavior: SpringAopBehaviorReason['behavior'];
+    readonly declaredOn: SpringAopBehaviorReason['declaredOn'];
+    readonly activation: SpringAopBehaviorReason['activation'];
+    readonly evidenceId: string;
+}
+export interface SpringAopAdviceMetadata {
+    readonly annotation: string;
+    readonly advice: SpringAopAdviceReason['advice'];
+    readonly pointcut: string;
+    readonly match: SpringAopAdviceReason['match'];
+    readonly activation: SpringAopAdviceReason['activation'];
+    readonly adviceId: string;
+    readonly adviceName?: string;
+    readonly adviceFilePath?: string;
+    readonly advisedId: string;
+    readonly advisedName?: string;
+    readonly advisedFilePath?: string;
+}
+export interface SpringAopUnresolvedPointcutMetadata {
+    readonly annotation: string;
+    readonly pointcut: string | null;
+    readonly adviceId: string;
+    readonly adviceName?: string;
+    readonly adviceFilePath?: string;
+    readonly evidenceId: string;
+}
+export interface SpringAopResolvedPointcutMetadata {
+    readonly annotation: string;
+    readonly pointcut: string;
+    readonly match: Extract<SpringAopPointcutReason['match'], 'static'>;
+    readonly resolution: Extract<SpringAopPointcutReason['resolution'], 'resolved'>;
+    readonly adviceId: string;
+    readonly adviceName?: string;
+    readonly adviceFilePath?: string;
+    readonly evidenceId: string;
+}
+export interface SpringAopAspectMetadata {
+    readonly annotation: string;
+    readonly activation: SpringAopAspectReason['activation'];
+    readonly registration: SpringAopAspectReason['registration'];
+    readonly evidenceId: string;
+}
+export interface SpringAopMetadata {
+    readonly framework: 'spring';
+    readonly proxied?: 'possible';
+    readonly truncated?: true;
+    readonly aspect?: SpringAopAspectMetadata;
+    readonly behaviors: readonly SpringAopBehaviorMetadata[];
+    readonly advices: readonly SpringAopAdviceMetadata[];
+    readonly resolvedPointcuts: readonly SpringAopResolvedPointcutMetadata[];
+    readonly unresolvedPointcuts: readonly SpringAopUnresolvedPointcutMetadata[];
+}
+/**
+ * Read additive Spring proxy/advice metadata for context and impact results.
+ *
+ * The helper intentionally trusts only versioned reasons accepted by the
+ * shared decoder. Other DECLARES edges (for example Spring Bean factories)
+ * and malformed/forward-version evidence are ignored. Query failures are
+ * fail-soft because older or partially upgraded indexes must remain readable.
+ */
+export declare function querySpringAopMetadata(lbugPath: string, symbolId: string, symbolType: string): Promise<SpringAopMetadata | undefined>;
+export {};

package/dist/mcp/local/aop-metadata.js

@@ -0,0 +1,227 @@
+import { executeParameterized } from '../../core/lbug/pool-adapter.js';
+import { decodeSpringAopReason, } from '../../core/ingestion/frameworks/spring/aop.js';
+const SUPPORTED_SYMBOL_TYPES = new Set(['Class', 'Interface', 'Method', 'CodeElement']);
+const QUERY_RESULT_LIMIT = 1_000;
+const QUERY_FETCH_LIMIT = QUERY_RESULT_LIMIT + 1;
+function readRowValue(row, name, index) {
+    if (typeof row === 'object' && row !== null && name in row) {
+        return row[name];
+    }
+    return Array.isArray(row) ? row[index] : undefined;
+}
+function readRequiredString(row, name, index) {
+    const value = readRowValue(row, name, index);
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function readOptionalString(row, name, index) {
+    const value = readRowValue(row, name, index);
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function normalizeRelationshipRow(row) {
+    const sourceId = readRequiredString(row, 'sourceId', 0);
+    const targetId = readRequiredString(row, 'targetId', 3);
+    if (sourceId === undefined || targetId === undefined)
+        return undefined;
+    const sourceName = readOptionalString(row, 'sourceName', 1);
+    const sourceFilePath = readOptionalString(row, 'sourceFilePath', 2);
+    const targetName = readOptionalString(row, 'targetName', 4);
+    const targetFilePath = readOptionalString(row, 'targetFilePath', 5);
+    return {
+        sourceId,
+        ...optionalField('sourceName', sourceName),
+        ...optionalField('sourceFilePath', sourceFilePath),
+        targetId,
+        ...optionalField('targetName', targetName),
+        ...optionalField('targetFilePath', targetFilePath),
+        reason: readRowValue(row, 'reason', 6),
+    };
+}
+function optionalField(key, value) {
+    return value === undefined ? {} : { [key]: value };
+}
+function stableDedupe(values, keyOf) {
+    const unique = new Map();
+    for (const value of values)
+        unique.set(keyOf(value), value);
+    return [...unique.entries()]
+        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+        .map(([, value]) => value);
+}
+const RELATIONSHIP_PROJECTION = `
+  RETURN source.id AS sourceId, source.name AS sourceName, source.filePath AS sourceFilePath,
+         target.id AS targetId, target.name AS targetName, target.filePath AS targetFilePath,
+         r.reason AS reason, r.step AS step
+`;
+const DETERMINISTIC_RELATIONSHIP_ORDER = 'ORDER BY sourceId, targetId, reason, step';
+/**
+ * Read additive Spring proxy/advice metadata for context and impact results.
+ *
+ * The helper intentionally trusts only versioned reasons accepted by the
+ * shared decoder. Other DECLARES edges (for example Spring Bean factories)
+ * and malformed/forward-version evidence are ignored. Query failures are
+ * fail-soft because older or partially upgraded indexes must remain readable.
+ */
+export async function querySpringAopMetadata(lbugPath, symbolId, symbolType) {
+    if (!SUPPORTED_SYMBOL_TYPES.has(symbolType))
+        return undefined;
+    try {
+        const [outgoingAdviceRows, incomingAdviceRows, outgoingPointcutRows, incomingPointcutRows] = await Promise.all([
+            executeParameterized(lbugPath, `MATCH (source {id: $symbolId})-[r:CodeRelation]->(target)
+           WHERE r.type = 'ADVISED_BY'
+             AND r.reason STARTS WITH 'spring-aop:v1:'
+           ${RELATIONSHIP_PROJECTION}
+           ${DETERMINISTIC_RELATIONSHIP_ORDER}
+           LIMIT 1001`, { symbolId }),
+            executeParameterized(lbugPath, `MATCH (source)-[r:CodeRelation]->(target {id: $symbolId})
+           WHERE r.type = 'ADVISED_BY'
+             AND r.reason STARTS WITH 'spring-aop:v1:'
+           ${RELATIONSHIP_PROJECTION}
+           ${DETERMINISTIC_RELATIONSHIP_ORDER}
+           LIMIT 1001`, { symbolId }),
+            executeParameterized(lbugPath, `MATCH (source {id: $symbolId})-[r:CodeRelation]->(target:CodeElement)
+           WHERE r.type = 'DECLARES'
+             AND r.reason STARTS WITH 'spring-aop:v1:'
+           ${RELATIONSHIP_PROJECTION}
+           ${DETERMINISTIC_RELATIONSHIP_ORDER}
+           LIMIT 1001`, { symbolId }),
+            executeParameterized(lbugPath, `MATCH (source)-[r:CodeRelation]->(target:CodeElement {id: $symbolId})
+           WHERE r.type = 'DECLARES'
+             AND r.reason STARTS WITH 'spring-aop:v1:'
+           ${RELATIONSHIP_PROJECTION}
+           ${DETERMINISTIC_RELATIONSHIP_ORDER}
+           LIMIT 1001`, { symbolId }),
+        ]);
+        const behaviors = [];
+        const advices = [];
+        const resolvedPointcuts = [];
+        const unresolvedPointcuts = [];
+        const aspects = [];
+        const truncated = [
+            outgoingAdviceRows,
+            incomingAdviceRows,
+            outgoingPointcutRows,
+            incomingPointcutRows,
+        ].some((rows) => rows.length >= QUERY_FETCH_LIMIT);
+        let queriedSymbolIsAdvisedSource = false;
+        for (const [rows, isOutgoing] of [
+            [outgoingAdviceRows, true],
+            [incomingAdviceRows, false],
+        ]) {
+            for (const rawRow of rows.slice(0, QUERY_RESULT_LIMIT)) {
+                const row = normalizeRelationshipRow(rawRow);
+                if (row === undefined)
+                    continue;
+                const reason = decodeSpringAopReason(row.reason);
+                if (reason?.kind === 'behavior') {
+                    if (isOutgoing)
+                        queriedSymbolIsAdvisedSource = true;
+                    behaviors.push({
+                        annotation: reason.annotation,
+                        behavior: reason.behavior,
+                        declaredOn: reason.declaredOn,
+                        activation: reason.activation,
+                        evidenceId: row.targetId,
+                    });
+                }
+                else if (reason?.kind === 'advice') {
+                    if (isOutgoing)
+                        queriedSymbolIsAdvisedSource = true;
+                    advices.push({
+                        annotation: reason.annotation,
+                        advice: reason.advice,
+                        pointcut: reason.pointcut,
+                        match: reason.match,
+                        activation: reason.activation,
+                        adviceId: row.targetId,
+                        ...optionalField('adviceName', row.targetName),
+                        ...optionalField('adviceFilePath', row.targetFilePath),
+                        advisedId: row.sourceId,
+                        ...optionalField('advisedName', row.sourceName),
+                        ...optionalField('advisedFilePath', row.sourceFilePath),
+                    });
+                }
+            }
+        }
+        for (const rows of [outgoingPointcutRows, incomingPointcutRows]) {
+            for (const rawRow of rows.slice(0, QUERY_RESULT_LIMIT)) {
+                const row = normalizeRelationshipRow(rawRow);
+                if (row === undefined)
+                    continue;
+                const reason = decodeSpringAopReason(row.reason);
+                if (reason?.kind === 'aspect') {
+                    aspects.push({
+                        annotation: reason.annotation,
+                        activation: reason.activation,
+                        registration: reason.registration,
+                        evidenceId: row.targetId,
+                    });
+                }
+                else if (reason?.kind === 'pointcut' &&
+                    reason.match === 'static' &&
+                    reason.resolution === 'resolved' &&
+                    typeof reason.pointcut === 'string') {
+                    resolvedPointcuts.push({
+                        annotation: reason.annotation,
+                        pointcut: reason.pointcut,
+                        match: reason.match,
+                        resolution: reason.resolution,
+                        adviceId: row.sourceId,
+                        ...optionalField('adviceName', row.sourceName),
+                        ...optionalField('adviceFilePath', row.sourceFilePath),
+                        evidenceId: row.targetId,
+                    });
+                }
+                else if (reason?.kind === 'pointcut' && reason.match === 'unresolved') {
+                    unresolvedPointcuts.push({
+                        annotation: reason.annotation,
+                        pointcut: reason.pointcut,
+                        adviceId: row.sourceId,
+                        ...optionalField('adviceName', row.sourceName),
+                        ...optionalField('adviceFilePath', row.sourceFilePath),
+                        evidenceId: row.targetId,
+                    });
+                }
+            }
+        }
+        const dedupedAspects = stableDedupe(aspects, (aspect) => JSON.stringify([aspect.annotation, aspect.evidenceId]));
+        const dedupedBehaviors = stableDedupe(behaviors, (behavior) => JSON.stringify([
+            behavior.behavior,
+            behavior.annotation,
+            behavior.declaredOn,
+            behavior.evidenceId,
+        ]));
+        const dedupedAdvices = stableDedupe(advices, (advice) => JSON.stringify([advice.advisedId, advice.adviceId, advice.advice, advice.pointcut]));
+        const dedupedPointcuts = stableDedupe(unresolvedPointcuts, (pointcut) => JSON.stringify([
+            pointcut.adviceId,
+            pointcut.evidenceId,
+            pointcut.annotation,
+            pointcut.pointcut,
+        ]));
+        const dedupedResolvedPointcuts = stableDedupe(resolvedPointcuts, (pointcut) => JSON.stringify([
+            pointcut.adviceId,
+            pointcut.evidenceId,
+            pointcut.annotation,
+            pointcut.pointcut,
+        ]));
+        if (dedupedAspects.length === 0 &&
+            dedupedBehaviors.length === 0 &&
+            dedupedAdvices.length === 0 &&
+            dedupedResolvedPointcuts.length === 0 &&
+            dedupedPointcuts.length === 0) {
+            return undefined;
+        }
+        return {
+            framework: 'spring',
+            ...(queriedSymbolIsAdvisedSource ? { proxied: 'possible' } : {}),
+            ...(truncated ? { truncated: true } : {}),
+            ...(dedupedAspects[0] === undefined ? {} : { aspect: dedupedAspects[0] }),
+            behaviors: dedupedBehaviors,
+            advices: dedupedAdvices,
+            resolvedPointcuts: dedupedResolvedPointcuts,
+            unresolvedPointcuts: dedupedPointcuts,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/mcp/local/bean-metadata.d.ts

@@ -1,2 +1,3 @@
 import { type SpringBeanMetadata } from '../../core/ingestion/frameworks/spring/bean-catalog.js';
-export declare function queryClassBeanMetadata(lbugPath: string, symbolId: string, symbolType: string): Promise<SpringBeanMetadata | undefined>;
+import { type SpringBeanFactoryMetadata } from '../../core/ingestion/frameworks/spring/bean-factories.js';
+export declare function queryClassBeanMetadata(lbugPath: string, symbolId: string, symbolType: string): Promise<SpringBeanMetadata | SpringBeanFactoryMetadata | undefined>;

package/dist/mcp/local/bean-metadata.js

@@ -1,9 +1,30 @@
 import { executeParameterized } from '../../core/lbug/pool-adapter.js';
 import { deriveSpringBeanMetadata, } from '../../core/ingestion/frameworks/spring/bean-catalog.js';
+import { decodeSpringBeanFactoryReason, } from '../../core/ingestion/frameworks/spring/bean-factories.js';
 export async function queryClassBeanMetadata(lbugPath, symbolId, symbolType) {
-    if (symbolType !== 'Class')
+    if (symbolType !== 'Class' && symbolType !== 'Method' && symbolType !== 'CodeElement') {
         return undefined;
+    }
     try {
+        if (symbolType !== 'Class') {
+            const pattern = symbolType === 'Method'
+                ? 'MATCH (m:Method {id: $symbolId})-[r:CodeRelation]->(b:CodeElement)'
+                : 'MATCH (m:Method)-[r:CodeRelation]->(b:CodeElement {id: $symbolId})';
+            // determinism: probe — PK-anchored singleton. A @Bean factory's declaration
+            // node id is derived from the declaring method's id
+            // (`CodeElement:spring-bean:<methodId>`, see bean-factories.ts), so exactly
+            // one DECLARES edge with this reason prefix exists per anchored endpoint,
+            // whichever end `$symbolId` pins.
+            const rows = await executeParameterized(lbugPath, `${pattern}
+         WHERE r.type = 'DECLARES'
+           AND r.reason STARTS WITH 'spring-bean-factory:'
+         RETURN r.reason AS reason
+         LIMIT 1`, { symbolId });
+            const row = rows[0];
+            return row === undefined ? undefined : decodeSpringBeanFactoryReason(row.reason ?? row[0]);
+        }
+        // determinism: probe — PK-anchored singleton. `$symbolId` is a node primary
+        // key, so at most one Class row can match and the LIMIT never chooses.
         const rows = await executeParameterized(lbugPath, `
       MATCH (c:Class {id: $symbolId})
       RETURN c.frameworkAnnotations AS frameworkAnnotations

package/dist/mcp/local/convex-metadata.d.ts

@@ -0,0 +1,8 @@
+import { executeParameterized } from '../../core/lbug/pool-adapter.js';
+export interface ConvexDispatchMetadata {
+    readonly factory?: string;
+    readonly boundary: string;
+    readonly staleIndex?: true;
+    readonly probeFailed?: true;
+}
+export declare function queryConvexDispatchMetadata(lbugPath: string, symbolId: string, symbolName: string, symbolType: string, runQuery?: typeof executeParameterized): Promise<ConvexDispatchMetadata | undefined>;