gitnexus 1.6.11-rc.8 → 1.6.11

package/dist/core/group/extractors/java-workspace-extractor.js

@@ -1,7 +1,20 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { XMLParser } from 'fast-xml-parser';
 import { shouldIgnorePath, loadIgnoreRules } from '../../../config/ignore-service.js';
 import { logger } from '../../logger.js';
+// POMs are static metadata. Parse hierarchy with a real XML parser, but do not
+// invoke Maven or resolve the effective model. Properties, profiles, and remote
+// parent resolution remain outside this extractor's deterministic boundary.
+const pomParser = new XMLParser({
+    ignoreAttributes: true,
+    removeNSPrefix: true,
+    trimValues: true,
+    parseTagValue: false,
+    processEntities: false,
+    ignoreDeclaration: true,
+    ignorePiTags: true,
+});
 async function parseJavaManifest(repoPath) {
     const pomPath = path.join(repoPath, 'pom.xml');
     try {
@@ -9,13 +22,14 @@ async function parseJavaManifest(repoPath) {
         return parsePom(content);
     }
     catch {
-        // fall through to Gradle
+        // Missing pom.xml — fall through to Gradle.
     }
+    const gradleSidecars = await readGradleSidecars(repoPath);
     for (const name of ['build.gradle.kts', 'build.gradle']) {
         const gradlePath = path.join(repoPath, name);
         try {
             const content = await fs.readFile(gradlePath, 'utf-8');
-            return parseGradle(content, repoPath);
+            return parseGradle(content, repoPath, gradleSidecars);
         }
         catch {
             continue;
@@ -23,45 +37,244 @@ async function parseJavaManifest(repoPath) {
     }
     return null;
 }
+async function readIfPresent(filePath) {
+    try {
+        return await fs.readFile(filePath, 'utf-8');
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readGradleSidecars(repoPath) {
+    const [properties, settingsKts, settingsGroovy, catalog] = await Promise.all([
+        readIfPresent(path.join(repoPath, 'gradle.properties')),
+        readIfPresent(path.join(repoPath, 'settings.gradle.kts')),
+        readIfPresent(path.join(repoPath, 'settings.gradle')),
+        readIfPresent(path.join(repoPath, 'gradle', 'libs.versions.toml')),
+    ]);
+    const sidecars = {
+        catalogLibraries: new Map(),
+        catalogBundles: new Map(),
+    };
+    const groupMatch = properties?.match(/(?:^|\n)\s*group\s*=\s*([^\s#]+)/);
+    if (groupMatch)
+        sidecars.propertiesGroup = groupMatch[1];
+    const settings = settingsKts ?? settingsGroovy;
+    const nameMatch = settings?.match(/rootProject\.name\s*=\s*['"]([^'"]+)['"]/);
+    if (nameMatch)
+        sidecars.rootProjectName = nameMatch[1];
+    if (catalog) {
+        const parsed = parseGradleVersionCatalog(catalog);
+        sidecars.catalogLibraries = parsed.libraries;
+        sidecars.catalogBundles = parsed.bundles;
+    }
+    return sidecars;
+}
+function catalogAccessors(alias) {
+    const dotted = alias.replace(/[-_]/g, '.');
+    const camel = alias.replace(/[-_]+([A-Za-z0-9])/g, (_, char) => char.toUpperCase());
+    return [...new Set([alias, dotted, camel])];
+}
+function projectAccessorToArtifactId(accessor) {
+    const last = accessor.split('.').pop();
+    return last.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`).replace(/^-/, '');
+}
+function moduleToGa(module) {
+    const parts = module.split(':');
+    return parts.length >= 2 ? `${parts[0]}:${parts[1]}` : undefined;
+}
+function parseInlineTomlTable(rhs) {
+    const fields = {};
+    for (const match of rhs.matchAll(/([A-Za-z0-9_-]+)\s*=\s*['"]([^'"]+)['"]/g)) {
+        fields[match[1]] = match[2];
+    }
+    return fields;
+}
+/** Default Gradle catalog (`gradle/libs.versions.toml`) — aliases only, no version resolution. */
+function parseGradleVersionCatalog(toml) {
+    const libraries = new Map();
+    const bundles = new Map();
+    let section = 'other';
+    const addLibrary = (alias, ga) => {
+        for (const accessor of catalogAccessors(alias))
+            libraries.set(accessor, ga);
+    };
+    for (const raw of toml.split(/\r?\n/)) {
+        const line = raw.replace(/#.*$/, '').trim();
+        if (!line)
+            continue;
+        const header = line.match(/^\[([^\]]+)\]$/);
+        if (header) {
+            const name = header[1];
+            section =
+                name === 'libraries' || name.endsWith('.libraries')
+                    ? 'libraries'
+                    : name === 'bundles' || name.endsWith('.bundles')
+                        ? 'bundles'
+                        : 'other';
+            continue;
+        }
+        if (section === 'libraries') {
+            const dottedModule = line.match(/^([A-Za-z0-9._-]+)\.module\s*=\s*['"]([^'"]+)['"]$/);
+            if (dottedModule) {
+                const ga = moduleToGa(dottedModule[2]);
+                if (ga)
+                    addLibrary(dottedModule[1], ga);
+                continue;
+            }
+            const assignment = line.match(/^([A-Za-z0-9._-]+)\s*=\s*(.+)$/);
+            if (!assignment)
+                continue;
+            const alias = assignment[1];
+            const rhs = assignment[2].trim();
+            const quoted = rhs.match(/^['"]([^'"]+)['"]$/);
+            if (quoted) {
+                const ga = moduleToGa(quoted[1]);
+                if (ga)
+                    addLibrary(alias, ga);
+                continue;
+            }
+            const table = parseInlineTomlTable(rhs);
+            const ga = table.module
+                ? moduleToGa(table.module)
+                : table.group && table.name
+                    ? `${table.group}:${table.name}`
+                    : undefined;
+            if (ga)
+                addLibrary(alias, ga);
+            continue;
+        }
+        if (section === 'bundles') {
+            const assignment = line.match(/^([A-Za-z0-9._-]+)\s*=\s*\[([^\]]*)\]$/);
+            if (!assignment)
+                continue;
+            const members = [...assignment[2].matchAll(/['"]([^'"]+)['"]/g)].map((match) => match[1]);
+            for (const accessor of catalogAccessors(assignment[1]))
+                bundles.set(accessor, members);
+        }
+    }
+    return { libraries, bundles };
+}
+const GRADLE_GROUP_PATTERNS = [
+    /(?:^|[\n{;])\s*(?:rootProject\.)?group\s*=\s*['"]([^'"]+)['"]/,
+    /(?:^|[\n{;])\s*group\s+['"]([^'"]+)['"]/,
+];
+const GRADLE_COORD_CONFIGS = 'implementation|api|compileOnly|runtimeOnly|testImplementation|testApi|testCompileOnly|compile|kapt|ksp|commonMainImplementation|commonMainApi';
+const CATALOG_ALIAS = '([A-Za-z0-9_]+(?:\\.[A-Za-z0-9_]+)*)(?:\\.get\\(\\)|\\.asProvider\\(\\))?';
+function gradleDepRe(suffix) {
+    return new RegExp(`(?:${GRADLE_COORD_CONFIGS})\\s*${suffix}`, 'g');
+}
+function parseGradleGroup(content) {
+    for (const pattern of GRADLE_GROUP_PATTERNS) {
+        const match = content.match(pattern);
+        if (match?.[1])
+            return match[1];
+    }
+    return undefined;
+}
+function asXmlNode(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function xmlText(value) {
+    if (typeof value === 'string' || typeof value === 'number') {
+        const text = String(value).trim();
+        return text || undefined;
+    }
+    const nested = asXmlNode(value)?.['#text'];
+    if (nested === undefined)
+        return undefined;
+    return xmlText(nested);
+}
+function xmlChildText(node, name) {
+    return node ? xmlText(node[name]) : undefined;
+}
+function asList(value) {
+    if (value === undefined || value === null)
+        return [];
+    return Array.isArray(value) ? value : [value];
+}
+/** Direct project dependencies only — not BOM, profiles, or plugin classpath. */
+function collectProjectDependencies(project, deps) {
+    const dependencies = asXmlNode(project.dependencies);
+    if (!dependencies)
+        return;
+    for (const dep of asList(dependencies.dependency)) {
+        const depNode = asXmlNode(dep);
+        const groupId = xmlChildText(depNode, 'groupId');
+        const artifactId = xmlChildText(depNode, 'artifactId');
+        if (groupId && artifactId)
+            deps.push(`${groupId}:${artifactId}`);
+    }
+}
 function parsePom(content) {
-    const projectGroupMatch = content.match(/<project[^>]*>[\s\S]*?<groupId>([^<]+)<\/groupId>/);
-    const projectArtifactMatch = content.match(/<project[^>]*>[\s\S]*?<artifactId>([^<]+)<\/artifactId>/);
-    if (!projectGroupMatch || !projectArtifactMatch)
+    let parsed;
+    try {
+        // parseSourceSafe guards tree-sitter's Windows SIGSEGV by switching to a
+        // chunked input callback above 16 KB; XMLParser only accepts XML text, so
+        // routing POMs through it silently yields an empty document.
+        // eslint-disable-next-line gitnexus/require-safe-parse
+        parsed = pomParser.parse(content);
+    }
+    catch {
         return null;
-    const groupId = projectGroupMatch[1].trim();
-    const artifactId = projectArtifactMatch[1].trim();
-    const deps = [];
-    const depBlocks = content.matchAll(/<dependency>\s*([\s\S]*?)<\/dependency>/g);
-    for (const block of depBlocks) {
-        const gMatch = block[1].match(/<groupId>([^<]+)<\/groupId>/);
-        const aMatch = block[1].match(/<artifactId>([^<]+)<\/artifactId>/);
-        if (gMatch && aMatch) {
-            deps.push(`${gMatch[1].trim()}:${aMatch[1].trim()}`);
-        }
     }
+    const project = asXmlNode(asXmlNode(parsed)?.project);
+    if (!project)
+        return null;
+    // Maven inherits groupId from <parent>, but artifactId is always the
+    // project's own direct child and must never fall back to parent.artifactId.
+    const groupId = xmlChildText(project, 'groupId') ?? xmlChildText(asXmlNode(project.parent), 'groupId');
+    const artifactId = xmlChildText(project, 'artifactId');
+    if (!groupId || !artifactId)
+        return null;
+    const deps = [];
+    collectProjectDependencies(project, deps);
     return { groupId, artifactId, deps: [...new Set(deps)] };
 }
-function parseGradle(content, repoPath) {
-    const groupMatch = content.match(/group\s*=\s*['"]([^'"]+)['"]/);
-    const dirName = path.basename(repoPath);
-    const groupId = groupMatch ? groupMatch[1] : '';
+function parseGradle(content, repoPath, sidecars = { catalogLibraries: new Map(), catalogBundles: new Map() }) {
+    // Static text + default catalog file. Do not execute Gradle.
+    const groupId = parseGradleGroup(content) ?? sidecars.propertiesGroup ?? '';
     if (!groupId)
         return null;
-    const artifactId = dirName;
+    const artifactId = sidecars.rootProjectName ?? path.basename(repoPath);
+    const { catalogLibraries, catalogBundles } = sidecars;
     const deps = [];
-    // implementation("group:artifact:version") or api("group:artifact:version")
-    const depMatches = content.matchAll(/(?:implementation|api|compileOnly|runtimeOnly)\s*\(\s*['"]([^'"]+)['"]\s*\)/g);
-    for (const m of depMatches) {
-        const parts = m[1].split(':');
-        if (parts.length >= 2) {
-            deps.push(`${parts[0]}:${parts[1]}`);
+    const pushCatalogAlias = (alias) => {
+        const ga = catalogLibraries.get(alias);
+        if (ga)
+            deps.push(ga);
+    };
+    const namedPattern = gradleDepRe(`(?:\\(\\s*)?(?:group\\s*=\\s*['"](?<group1>[^'"]+)['"]\\s*,\\s*name\\s*=\\s*['"](?<name1>[^'"]+)['"]|name\\s*=\\s*['"](?<name2>[^'"]+)['"]\\s*,\\s*group\\s*=\\s*['"](?<group2>[^'"]+)['"]|group:\\s*['"](?<group3>[^'"]+)['"]\\s*,\\s*name:\\s*['"](?<name3>[^'"]+)['"]|name:\\s*['"](?<name4>[^'"]+)['"]\\s*,\\s*group:\\s*['"](?<group4>[^'"]+)['"])`);
+    for (const match of content.matchAll(namedPattern)) {
+        const group = match.groups?.group1 ?? match.groups?.group2 ?? match.groups?.group3 ?? match.groups?.group4;
+        const name = match.groups?.name1 ?? match.groups?.name2 ?? match.groups?.name3 ?? match.groups?.name4;
+        if (group && name)
+            deps.push(`${group}:${name}`);
+    }
+    for (const match of content.matchAll(gradleDepRe(`(?:\\(\\s*)?libs(?:\\.libraries)?\\.(?!bundles\\.|plugins\\.)${CATALOG_ALIAS}`))) {
+        pushCatalogAlias(match[1]);
+    }
+    for (const match of content.matchAll(gradleDepRe(`(?:\\(\\s*)?libs\\.bundles\\.${CATALOG_ALIAS}`))) {
+        for (const member of catalogBundles.get(match[1]) ?? []) {
+            for (const accessor of catalogAccessors(member))
+                pushCatalogAlias(accessor);
         }
     }
-    // implementation(project(":subproject"))
-    const projDeps = content.matchAll(/(?:implementation|api)\s*\(\s*project\s*\(\s*['"]([^'"]+)['"]\s*\)\s*\)/g);
-    for (const m of projDeps) {
-        const subName = m[1].replace(/^:/, '');
-        deps.push(`${groupId}:${subName}`);
+    for (const match of content.matchAll(gradleDepRe(`\\(\\s*projects\\.([A-Za-z][A-Za-z0-9.]*)`))) {
+        deps.push(`${groupId}:${projectAccessorToArtifactId(match[1])}`);
+    }
+    for (const match of content.matchAll(gradleDepRe(`(?:\\(\\s*['"]([^'"]+)['"]\\s*\\)|['"]([^'"]+)['"])`))) {
+        const coord = match[1] ?? match[2];
+        if (!coord)
+            continue;
+        const parts = coord.split(':');
+        if (parts.length >= 2)
+            deps.push(`${parts[0]}:${parts[1]}`);
+    }
+    for (const match of content.matchAll(gradleDepRe(`(?:\\(\\s*)?project\\s*\\(\\s*['"]([^'"]+)['"]\\s*\\)`))) {
+        deps.push(`${groupId}:${match[1].replace(/^:/, '')}`);
     }
     return { groupId, artifactId, deps: [...new Set(deps)] };
 }

package/dist/core/group/group-lock.js

@@ -21,12 +21,11 @@
  * else claims: group directories live under `~/.gitnexus/groups/<name>` (or
  * `$GITNEXUS_HOME`), never under a repo's `.gitnexus[/branches/<slug>]`.
  *
- * WHY IT FAILS CLOSED, unlike the registry lock. `withRegistryLock` degrades to
- * running UNLOCKED on timeout, and that is right for it: it guards a sub-second
- * JSON read/merge/write on a latency-critical path (`augment` runs on every
- * editor tool call), and running unlocked is merely the pre-lock status quo. A
- * group sync is the opposite on every axis — it is long, expensive, operator-
- * initiated, and its lost update destroys contracts rather than a registry field.
+ * WHY IT FAILS CLOSED, like the registry lock. `withRegistryLock` also
+ * refuses to continue unlocked on timeout: a lost registry update can drop a
+ * concurrent registration. A group sync still fails closed for additional
+ * reasons — it is long, expensive, operator-initiated, and a lost update
+ * destroys contracts rather than a registry field.
  * A sync that cannot be protected must not run at all, and there are three
  * distinct ways it can fail to be protected; all three throw
  * {@link GroupSyncLockError}:

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

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

package/dist/core/group/normalization.js

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

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

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

package/dist/core/group/service.js

@@ -301,8 +301,9 @@ export class GroupService {
         // group tools never need it — so deferring it here keeps that closure off
         // MCP server startup entirely and off every non-sync group call. The CLI
         // already does exactly this at `cli/group.ts`'s sync command.
-        const { syncGroup } = await import('./sync.js');
+        const { syncGroup, formatGroupSyncAmbiguousError } = await import('./sync.js');
         const { GroupSyncLockError } = await import('./group-lock.js');
+        const { RegistryAmbiguousTargetError } = await import('../../storage/repo-manager.js');
         let result;
         try {
             result = await syncGroup(config, {
@@ -315,6 +316,9 @@ export class GroupService {
             });
         }
         catch (err) {
+            if (err instanceof RegistryAmbiguousTargetError) {
+                return { error: formatGroupSyncAmbiguousError(err) };
+            }
             // Fails closed (R9): this sync could not be protected against a concurrent
             // one, so it did not run and wrote nothing. Return it through the same
             // error channel a missing group uses — NEVER as a success payload of zeroes,
@@ -337,6 +341,14 @@ export class GroupService {
             // can otherwise see contract counts that disagree with this payload, with
             // nothing here explaining why the write was skipped.
             registryOutcome: result.registryOutcome,
+            // Data-quality signals surfaced from the sync run: links whose provider
+            // endpoint never resolved to a graph symbol, per-repo extraction
+            // failures with reasons, and operator warnings (e.g. bridge.lbug write
+            // failed after contracts.json was written). Always present so MCP
+            // consumers can branch on them without existence checks.
+            degradedLinks: result.degradedLinks,
+            failedRepos: result.failedRepos,
+            warnings: result.warnings,
         };
     }
     async groupContracts(params) {

package/dist/core/group/storage.js

@@ -1,11 +1,11 @@
 import * as fs from 'node:fs';
 import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
-import * as os from 'node:os';
 import { writeFileAtomic } from '../../storage/fs-atomic.js';
+import { getGlobalDir } from '../../storage/global-dir.js';
 export const CONTRACTS_FILE = 'contracts.json';
 export function getDefaultGitnexusDir() {
-    return process.env.GITNEXUS_HOME || path.join(os.homedir(), '.gitnexus');
+    return getGlobalDir();
 }
 export function getGroupsBaseDir(gitnexusDir) {
     return path.join(gitnexusDir || getDefaultGitnexusDir(), 'groups');

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

@@ -1,4 +1,4 @@
-import { type RegistryEntry } from '../../storage/repo-manager.js';
+import { RegistryAmbiguousTargetError, type RegistryEntry } from '../../storage/repo-manager.js';
 import type { GroupConfig, RepoHandle, RepoSnapshot, StoredContract, CrossLink, GroupManifestLink, MatchType } from './types.js';
 export interface SyncOptions {
     extractorOverride?: ((repo: RepoHandle) => Promise<StoredContract[]>) | (() => Promise<StoredContract[]>);
@@ -47,6 +47,27 @@ export interface SyncResult {
      * none of that repo's contracts are in `contracts`.
      */
     unreadableRepos: string[];
+    /**
+     * Cross-links whose provider endpoint has no resolved graph symbol
+     * (`degraded: true` on the link — see `isUnresolvedEndpoint`). The boundary
+     * is proven but cross-impact fan-out cannot anchor it; the usual remedy is
+     * re-analyzing the provider repo so its handlers resolve.
+     */
+    degradedLinks: number;
+    /**
+     * Repos whose per-repo extraction threw (init, an extractor, or the
+     * snapshot read). Each still lands in `unreadableRepos` (group path) —
+     * unchanged downstream semantics — but carries its failure reason here: the
+     * catch used to swallow the exception, leaving contracts already pushed by
+     * earlier extractors in this iteration as silent half-repo data. `repo` is
+     * that same group path (e.g. `app/backend`), not the registry display name.
+     */
+    failedRepos: Array<{
+        repo: string;
+        reason: string;
+    }>;
+    /** Operator-facing run warnings (e.g. bridge.lbug write failed after contracts.json was written). */
+    warnings: string[];
     repoSnapshots: Record<string, RepoSnapshot>;
     /**
      * Matching stages this run was asked to skip. Populated on EVERY outcome,
@@ -64,6 +85,8 @@ export interface SyncResult {
     registryOutcome: RegistryWriteOutcome;
 }
 export declare function stableRepoPoolId(entry: RegistryEntry, allEntries: RegistryEntry[]): string;
+/** Operator copy for group sync — unique `--name`, not a path in yaml. */
+export declare function formatGroupSyncAmbiguousError(err: RegistryAmbiguousTargetError): string;
 /** A batch of manifest links whose referenced in-group repos fit one resident window. */
 export interface ManifestWindow {
     links: GroupManifestLink[];