gitnexus 1.6.9-rc.7 → 1.6.9-rc.9

package/dist/core/group/bridge-db.js

@@ -171,11 +171,19 @@ export async function closeBridgeDb(handle) {
     // pending on disk, which makes a subsequent read-side open either race
     // with the WAL replay or trip the database-id check on the sidecars.
     // CHECKPOINT is a no-op when there's nothing pending, so it's cheap.
-    try {
-        await handle._conn.query('CHECKPOINT');
-    }
-    catch {
-        /* ignore — older LadybugDB or schemaless DB may not accept it */
+    //
+    // ONLY on a writable handle. A read-only connection has nothing to flush,
+    // and issuing CHECKPOINT on it leaves a WAL/shadow lock artifact that makes
+    // the very next read-only open of the same path fail in-process — which broke
+    // repeated `@group` impact/trace calls in a long-lived MCP server (the read
+    // path opens read-only, queries, and closes per call).
+    if (!handle._readOnly) {
+        try {
+            await handle._conn.query('CHECKPOINT');
+        }
+        catch {
+            /* ignore — older LadybugDB or schemaless DB may not accept it */
+        }
     }
     try {
         await handle._conn.close();
@@ -189,6 +197,16 @@ export async function closeBridgeDb(handle) {
     catch {
         /* ignore */
     }
+    // NOTE: Windows in-process write→read reopen of the SAME bridge.lbug is still a
+    // known limitation (the writable close's OS file handle is not released before
+    // the read open races; the existing open-side LBUG_OPEN_RETRY only retries
+    // lock-pattern errors, not the post-rename sidecar database-id mismatch). The
+    // bridge's close-then-reopen tests stay Windows-skipped. A close-side
+    // waitForWindowsHandleRelease + finalizeLbugSidecarsAfterClose probe (mirroring
+    // safeClose) was tried and did NOT close that gap on Windows CI, so it was
+    // removed rather than carry latency/duplication for no Windows benefit. The
+    // read-only CHECKPOINT skip above is the load-bearing fix and works on
+    // Linux/macOS (the platforms where in-process reopen is supported).
 }
 /* ------------------------------------------------------------------ */
 /*  retryRename — handles transient EBUSY/EPERM/EACCES on Windows    */
@@ -577,7 +595,7 @@ export async function openBridgeDbReadOnly(groupDir) {
             // (where we can retry) instead of on the first user query.
             await handle.db.init();
             await handle.conn.init();
-            return { _db: handle.db, _conn: handle.conn, groupDir };
+            return { _db: handle.db, _conn: handle.conn, groupDir, _readOnly: true };
         }
         catch (err) {
             lastErr = err;

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

@@ -2,12 +2,21 @@
  * Cross-repo impact (Phase 1 local walk + Phase 2 bridge fan-out).
  * All bridge Cypher for this feature lives in this module.
  */
-import type { CrossRepoImpact, GroupImpactResult } from './types.js';
+import type { BridgeHandle, CrossRepoImpact, GroupImpactResult } from './types.js';
 import type { GroupToolPort } from './service.js';
 /** Cross-boundary hops beyond this value are clamped (multi-hop reserved for future work). */
 export declare const MAX_SUPPORTED_CROSS_DEPTH = 1;
 /** Default wall-clock budget for the Phase 1 `impact` leg when callers omit `timeoutMs`. */
 export declare const DEFAULT_LOCAL_IMPACT_TIMEOUT_MS = 30000;
+export type BridgeNeighborRow = {
+    neighborRepo: string;
+    neighborUid: string;
+    neighborFilePath?: string;
+    matchType: string;
+    confidence: number;
+    contractId: string;
+    contractType: string;
+};
 export interface RunGroupImpactDeps {
     port: GroupToolPort;
     gitnexusDir: string;
@@ -80,6 +89,30 @@ export declare function collectImpactSymbolUids(local: unknown, servicePrefix: s
     targetFilePath?: string;
 };
 export declare function mergeRisk(localRisk: string, cross: CrossRepoImpact[]): string;
+export declare function ensureBridgeReady(groupDir: string): Promise<{
+    handle: BridgeHandle;
+} | {
+    error: string;
+}>;
+/**
+ * Resolve cross-repo neighbors over `ContractLink` for a set of local symbol
+ * UIDs, in a single direction, sorted by descending confidence.
+ *
+ * This is the one shared consumer↔provider bridge join. `runGroupImpact`'s
+ * Phase-2 fan-out uses it directly; the cross-repo trace path (`cross-trace.ts`)
+ * reuses the same `queryBridge` + row-normalization primitives but issues a
+ * distinct *pair* query, because a trace must keep BOTH endpoints of a crossing
+ * (this neighbor join intentionally returns only the far side, which is lossy
+ * for stitching a path). Keeping this helper as the single uid-filtered join
+ * means impact never forks its own copy of the neighbor Cypher.
+ *
+ * Returns `[]` for an empty `uids` set without touching the DB.
+ */
+export declare function resolveBridgeNeighbors(handle: BridgeHandle, opts: {
+    localRepo: string;
+    uids: string[];
+    direction: 'upstream' | 'downstream';
+}): Promise<BridgeNeighborRow[]>;
 export declare function runGroupImpact(deps: RunGroupImpactDeps, params: Record<string, unknown>): Promise<GroupImpactResult | {
     error: string;
 }>;

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

@@ -267,7 +267,7 @@ export function mergeRisk(localRisk, cross) {
         return 'MEDIUM';
     return localRisk;
 }
-async function ensureBridgeReady(groupDir) {
+export async function ensureBridgeReady(groupDir) {
     const meta = await readBridgeMeta(groupDir);
     if (meta.version > 0 && meta.version !== BRIDGE_SCHEMA_VERSION) {
         return {
@@ -306,6 +306,37 @@ function rowToNeighbor(r) {
         contractType: String(r.contractType ?? r[6] ?? 'custom'),
     };
 }
+/**
+ * Resolve cross-repo neighbors over `ContractLink` for a set of local symbol
+ * UIDs, in a single direction, sorted by descending confidence.
+ *
+ * This is the one shared consumer↔provider bridge join. `runGroupImpact`'s
+ * Phase-2 fan-out uses it directly; the cross-repo trace path (`cross-trace.ts`)
+ * reuses the same `queryBridge` + row-normalization primitives but issues a
+ * distinct *pair* query, because a trace must keep BOTH endpoints of a crossing
+ * (this neighbor join intentionally returns only the far side, which is lossy
+ * for stitching a path). Keeping this helper as the single uid-filtered join
+ * means impact never forks its own copy of the neighbor Cypher.
+ *
+ * Returns `[]` for an empty `uids` set without touching the DB.
+ */
+export async function resolveBridgeNeighbors(handle, opts) {
+    if (opts.uids.length === 0)
+        return [];
+    const cypher = opts.direction === 'upstream' ? CY_NEIGHBORS_UPSTREAM : CY_NEIGHBORS_DOWNSTREAM;
+    const rows = await queryBridge(handle, cypher, {
+        localRepo: opts.localRepo,
+        uids: opts.uids,
+    });
+    const neighbors = [];
+    for (const raw of rows) {
+        const n = rowToNeighbor(raw);
+        if (n)
+            neighbors.push(n);
+    }
+    neighbors.sort((a, b) => b.confidence - a.confidence);
+    return neighbors;
+}
 export async function runGroupImpact(deps, params) {
     const parsed = validateGroupImpactParams(params);
     if (parsed.ok === false)
@@ -418,18 +449,11 @@ export async function runGroupImpact(deps, params) {
     const outOfScope = [];
     const truncatedRepos = [];
     try {
-        const cypher = direction === 'upstream' ? CY_NEIGHBORS_UPSTREAM : CY_NEIGHBORS_DOWNSTREAM;
-        const rows = await queryBridge(handle, cypher, {
+        const neighbors = await resolveBridgeNeighbors(handle, {
             localRepo: repoPath,
             uids,
+            direction,
         });
-        const neighbors = [];
-        for (const raw of rows) {
-            const n = rowToNeighbor(raw);
-            if (n)
-                neighbors.push(n);
-        }
-        neighbors.sort((a, b) => b.confidence - a.confidence);
         const seen = new Set();
         for (const n of neighbors) {
             if (servicePrefix && !fileMatchesServicePrefix(n.neighborFilePath, servicePrefix)) {

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

@@ -0,0 +1,135 @@
+/**
+ * Cross-repo call trace.
+ *
+ * Stitches per-repo directed-path segments (CALLS + HAS_METHOD, via the
+ * existing single-repo `trace`) across a single `ContractLink` boundary in the
+ * group bridge, and — when a `--pdg` layer is present and the caller opts in —
+ * enriches the boundary-adjacent segments with their intra-procedural
+ * REACHING_DEF data-flow.
+ *
+ * Design notes:
+ *  - The crossing is a single bridge hop joined on `symbolUid` (the symbol node
+ *    id is the same value the bridge stores as `Contract.symbolUid`). This
+ *    mirrors `cross-impact.ts` and is clamped to one boundary
+ *    (`MAX_SUPPORTED_CROSS_DEPTH`); multi-hop is deferred.
+ *  - All trace-specific bridge Cypher lives in THIS module (mirroring the
+ *    "all bridge Cypher for this feature lives here" convention in
+ *    cross-impact.ts). The trace needs BOTH endpoints of a crossing to stitch a
+ *    path, so it issues its own pair query rather than the lossy uid-filtered
+ *    neighbor join exported by cross-impact (`resolveBridgeNeighbors`), which
+ *    intentionally returns only the far side.
+ *  - PDG is enrichment only: data flow never crosses the repo boundary. Full
+ *    cross-program (SDG-like) data flow is deferred — see
+ *    docs/plans/2026-06-18-002-feat-unified-pdg-impact-evaluation-plan.md.
+ */
+import type { GroupPdgFlowHop, GroupToolPort } from './service.js';
+export interface TraceHop {
+    name: string;
+    filePath: string;
+    startLine: number;
+    /** The member repo path (group.yaml key) this hop belongs to. */
+    repo: string;
+}
+export interface TraceEdge {
+    relType: string;
+    confidence: number;
+}
+export interface SegmentDataFlow {
+    /** Member repo path of the enriched segment. */
+    repo: string;
+    /** The boundary-adjacent symbol the flow was anchored on. */
+    anchor: string;
+    variable?: string;
+    hops: GroupPdgFlowHop[];
+    truncated?: boolean;
+}
+export interface BridgeCrossing {
+    fromRepo: string;
+    toRepo: string;
+    contractId: string;
+    contractType: string;
+    matchType: string;
+    confidence: number;
+}
+export interface GroupTraceEndpoint {
+    name: string;
+    filePath: string;
+    startLine: number;
+    repo: string;
+}
+export interface GroupTraceOkResult {
+    status: 'ok';
+    group: string;
+    from: GroupTraceEndpoint;
+    to: GroupTraceEndpoint;
+    /** 0 for a same-repo trace, 1 for a single boundary crossing. */
+    crossings: BridgeCrossing[];
+    hopCount: number;
+    hops: TraceHop[];
+    edges: TraceEdge[];
+    /** Present only when PDG enrichment ran for at least one segment. */
+    dataFlow?: SegmentDataFlow[];
+    truncated?: boolean;
+    notes: string[];
+}
+export interface GroupTraceCandidate {
+    repo: string;
+    id: string;
+    name: string;
+    filePath: string;
+    startLine: number;
+}
+export interface GroupTraceNotFoundResult {
+    status: 'not_found';
+    group: string;
+    role?: 'from' | 'to';
+    query?: string;
+    /**
+     * True when the answer is NOT authoritative: the crossing cap
+     * (`MAX_CROSSINGS_TO_TRY`) was hit, so a connecting ContractLink ranked beyond
+     * the cap may have been skipped. A consumer should treat this as "unknown",
+     * not "no path exists".
+     */
+    truncated?: boolean;
+    notes: string[];
+    suggestion?: string;
+}
+export interface GroupTraceAmbiguousResult {
+    status: 'ambiguous';
+    group: string;
+    role: 'from' | 'to';
+    candidates: GroupTraceCandidate[];
+    notes: string[];
+}
+export interface GroupTraceErrorResult {
+    status: 'error';
+    group: string;
+    error: string;
+    notes: string[];
+}
+export type GroupTraceResult = GroupTraceOkResult | GroupTraceNotFoundResult | GroupTraceAmbiguousResult | GroupTraceErrorResult;
+/**
+ * Centralized degraded-state messages so wording stays consistent and
+ * testable. Kept as named constants/builders rather than inline strings.
+ */
+export declare const TRACE_NOTES: {
+    readonly noBridgeLink: string;
+    readonly crossDepthClamped: string;
+    readonly noLocalPath: (repo: string) => string;
+    readonly noPdgLayer: (repo: string) => string;
+    readonly pdgRequested: string;
+    readonly pdgSameRepoNoop: string;
+    readonly crossingsCapped: (cap: number) => string;
+    readonly degradedMembers: (repos: string[]) => string;
+    readonly fileBoundaryFallback: string;
+    readonly anonymousHandler: (route: string, location: string) => string;
+    readonly destinationNoLink: string;
+    readonly destinationNoReach: string;
+    readonly destinationMultiple: string;
+    readonly destinationAmbiguousFile: string;
+};
+export interface RunGroupTraceDeps {
+    port: GroupToolPort;
+    gitnexusDir: string;
+}
+export declare function runGroupTrace(deps: RunGroupTraceDeps, params: Record<string, unknown>): Promise<GroupTraceResult>;