gitnexus 1.6.10-rc.225 → 1.6.10-rc.227

package/dist/cli/group.js

@@ -148,6 +148,16 @@ export function registerGroupCommands(program) {
             if ((st.missingRepos || []).length > 0) {
                 console.log(`\n  Last sync missing repos: ${st.missingRepos.join(', ')}`);
             }
+            // Only the populated case prints. Absent means a registry that predates
+            // the field, and empty is the ordinary clean sync — neither is worth a
+            // line, whereas a narrowed registry changes how every later answer
+            // should be read.
+            const skippedStages = st.suppressedMatchStages ?? [];
+            if (skippedStages.length > 0) {
+                console.log(`\n  Last sync skipped matching stages: ${skippedStages.join(', ')}` +
+                    `\n     Cross-links those stages would have found are absent by request.` +
+                    `\n     Re-run \`gitnexus group sync\` without --exact-only for the complete set.`);
+            }
         }
         finally {
             await backend.dispose().catch(() => { });
@@ -156,10 +166,8 @@ export function registerGroupCommands(program) {
     group
         .command('sync <name>')
         .description('Sync Contract Registry — extract contracts and build cross-links')
-        .option('--skip-embeddings', 'Exact + BM25 only (no embedding fallback)')
-        .option('--exact-only', 'Exact match only')
-        .option('--allow-stale', 'Skip stale index warnings')
-        .option('--verbose', 'Show each cross-link detail')
+        .option('--exact-only', 'Skip wildcard service matching; cross-link on exact contract-id match only (manifest links still apply)')
+        .option('--verbose', 'Show additional sync diagnostics')
         .option('--json', 'JSON output')
         .action(async (name, opts) => {
         const { getGroupDir, getDefaultGitnexusDir } = await import('../core/group/storage.js');
@@ -173,9 +181,7 @@ export function registerGroupCommands(program) {
         try {
             result = await syncGroup(config, {
                 groupDir,
-                allowStale: Boolean(opts.allowStale),
                 verbose: Boolean(opts.verbose),
-                skipEmbeddings: Boolean(opts.skipEmbeddings),
                 exactOnly: Boolean(opts.exactOnly),
             });
         }
@@ -212,10 +218,41 @@ export function registerGroupCommands(program) {
                 console.log(`\n  ⚠️ Not found in the registry: ${result.missingRepos.join(', ')}` +
                     `\n     Index them with \`gitnexus analyze\`, or remove them from group.yaml.`);
             }
-            console.log(`\nMatching cascade:`);
-            const exactLinks = result.crossLinks.filter((l) => l.matchType === 'exact');
-            console.log(`  exact:     ${exactLinks.length} cross-links (confidence 1.0)`);
-            console.log(`  unmatched: ${result.unmatched.length} contracts`);
+            // Every stage that produced a link, not just `exact`. This used to print
+            // `Matching cascade:` and then count `exact` alone, while the `Wrote
+            // contracts.json (…)` line below reports `result.crossLinks.length` —
+            // which also includes `manifest` and `wildcard` links. For any group with
+            // those, the two numbers disagreed with nothing on screen explaining why.
+            // Summing the stages here makes them reconcile by construction.
+            console.log(`\nMatching:`);
+            // Exhaustive by construction, same idiom as OUTCOME_LINE below: adding a
+            // MatchType fails the build here instead of silently going uncounted and
+            // reopening the very mismatch this replaced. Every stage prints even at
+            // zero — a stage that is absent reads as "did not apply", not "found none".
+            const STAGE_COUNTS = {
+                exact: 0,
+                manifest: 0,
+                wildcard: 0,
+            };
+            for (const link of result.crossLinks)
+                STAGE_COUNTS[link.matchType] += 1;
+            // A stage the sync was told to skip is reported as skipped, not as a
+            // zero count. The two are different facts — "ran, matched nothing" and
+            // "never ran" — and printing both as `0` is the same conflation this
+            // block replaced. Driven by what the sync did (`suppressedMatchStages`)
+            // rather than by what the caller asked for, so it stays correct on the
+            // outcomes where the run ended without writing a registry.
+            for (const stage of Object.keys(STAGE_COUNTS)) {
+                const count = STAGE_COUNTS[stage];
+                const label = `${stage}:`.padEnd(10);
+                if (result.suppressedMatchStages.includes(stage)) {
+                    console.log(`  ${label} skipped (--exact-only)`);
+                    continue;
+                }
+                const confidence = stage === 'exact' ? ' (confidence 1.0)' : '';
+                console.log(`  ${label} ${count} cross-links${confidence}`);
+            }
+            console.log(`  ${'unmatched:'.padEnd(10)} ${result.unmatched.length} contracts`);
             // Driven by what actually happened to the file. This line used to be
             // unconditional, so a run that deliberately preserved the previous
             // registry still announced `Wrote contracts.json (0 contracts, 0
@@ -330,9 +367,28 @@ export function registerGroupCommands(program) {
                     // repos — reporting it as crossings understates a fan-out cap the
                     // same way #2787's totals did.
                     const dropped = raw?.truncatedRepos ?? [];
-                    console.log(dropped.length > 0
-                        ? `  risk is a LOWER BOUND — fan-out stopped early; crossings to ${dropped.length} repo(s) not traversed: ${dropped.join(', ')}`
-                        : '  risk is a LOWER BOUND — the local impact walk did not complete (every bridge crossing was traversed)');
+                    const reason = raw?.truncationReason;
+                    // Keyed on the REASON, not on which incidental fact happens to be
+                    // non-empty. `truncatedRepos` is populated for a structural gap too
+                    // — the bridge's incomplete repos are unioned into it even when ZERO
+                    // crossings were attempted — so branching on its length first
+                    // reported "fan-out stopped early" for a run where nothing stopped
+                    // early, and omitted the only remedy that works. Same false-cause
+                    // shape the contract listing was just re-gated for, one command over.
+                    const floorReason = () => {
+                        if (reason === 'suppressed-stage') {
+                            return 'the last sync skipped a matching stage (--exact-only); re-run `gitnexus group sync` without it for the complete graph';
+                        }
+                        if (reason === 'incomplete-sync') {
+                            return dropped.length > 0
+                                ? `the last sync could not account for ${dropped.join(', ')}; their contracts are absent from every query against this bridge — re-run \`gitnexus group sync\``
+                                : 'the last sync could not say which repos it read — re-run `gitnexus group sync`';
+                        }
+                        return dropped.length > 0
+                            ? `fan-out stopped early; crossings to ${dropped.length} repo(s) not traversed: ${dropped.join(', ')}`
+                            : 'the local impact walk did not complete (every bridge crossing was traversed)';
+                    };
+                    console.log(`  risk is a LOWER BOUND — ${floorReason()}`);
                 }
             }
         }
@@ -402,7 +458,7 @@ export function registerGroupCommands(program) {
                 process.exitCode = 1;
                 return;
             }
-            const { contracts, crossLinks, truncated, unreadableRepos, missingRepos } = raw;
+            const { contracts, crossLinks, truncated, unreadableRepos, missingRepos, suppressedMatchStages, truncationReason, } = raw;
             if (opts.json) {
                 // The whole payload, not a re-serialized subset. Destructuring the two
                 // fields this command happens to print and rebuilding an object from
@@ -421,7 +477,25 @@ export function registerGroupCommands(program) {
                 for (const l of crossLinks) {
                     console.log(`  ${l.from.repo} -> ${l.to.repo}  [${l.matchType}, conf=${l.confidence}]  ${l.contractId}`);
                 }
-                if (truncated) {
+                // Separate from `truncated` below, and deliberately so: that one means
+                // the sync could not read something and the remedy is to fix the repo.
+                // This one means the sync was ASKED to skip a stage, and the remedy is
+                // to re-run without the flag. A listing narrowed on purpose is still
+                // narrowed, and without this the human view showed nothing at all.
+                if (suppressedMatchStages && suppressedMatchStages.length > 0) {
+                    console.log(`\n⚠️ This listing is a lower bound: the last sync skipped ${suppressedMatchStages.join(', ')} matching` +
+                        `\n   (--exact-only), so cross-links that stage would have found are absent.` +
+                        `\n   Re-run \`gitnexus group sync\` without --exact-only for the complete set.`);
+                }
+                // Gated on the REASON, not just the flag. A suppressed stage sets
+                // `truncated` with both repo lists empty, which sent this block down
+                // its else-branch and printed "the last sync did not record which
+                // repos it could read" — a false statement, with the wrong remedy,
+                // about a sync that recorded them fine. The suppressed-stage warning
+                // above already said the true thing. When a repo gap co-occurs the
+                // reason is 'incomplete-sync' (the repo side takes precedence in
+                // `crossRepoCompleteness`), so this block still runs for it.
+                if (truncated && truncationReason !== 'suppressed-stage') {
                     // Counts above are a floor, not a census. Name the repos when the
                     // registry recorded them, and say so plainly when it did not — a
                     // listing that cannot say what it is missing is still incomplete.

package/dist/cli/help-i18n.js

@@ -151,9 +151,7 @@ const OPTION_DESCRIPTION_KEYS = {
     'embeddings install|--cuda': 'help.option.embeddings.install.cuda',
     'embeddings install|--force': 'help.option.embeddings.install.force',
     'group create|--force': 'help.option.group.create.force',
-    'group sync|--skip-embeddings': 'help.option.group.sync.skipEmbeddings',
     'group sync|--exact-only': 'help.option.group.sync.exactOnly',
-    'group sync|--allow-stale': 'help.option.group.sync.allowStale',
     'group sync|--verbose': 'help.option.group.sync.verbose',
     'group sync|--json': 'help.option.json',
     'group impact|--target <symbol>': 'help.option.group.impact.target',

package/dist/cli/i18n/en.d.ts

@@ -233,10 +233,8 @@ export declare const en: {
     readonly 'help.option.embeddings.install.cuda': "Also download the CUDA GPU binaries (runs onnxruntime-node's NuGet postinstall; set GLOBAL_AGENT_HTTPS_PROXY behind a proxy)";
     readonly 'help.option.embeddings.install.force': "Install into the runtime prefix even when the stack already resolves";
     readonly 'help.option.group.create.force': "Overwrite existing group";
-    readonly 'help.option.group.sync.skipEmbeddings': "Exact + BM25 only (no embedding fallback)";
-    readonly 'help.option.group.sync.exactOnly': "Exact match only";
-    readonly 'help.option.group.sync.allowStale': "Skip stale index warnings";
-    readonly 'help.option.group.sync.verbose': "Show each cross-link detail";
+    readonly 'help.option.group.sync.exactOnly': "Skip wildcard service matching; cross-link on exact contract-id match only (manifest links still apply)";
+    readonly 'help.option.group.sync.verbose': "Show additional sync diagnostics";
     readonly 'help.option.status.json': "Emit machine-readable index and analyzer provenance";
     readonly 'help.option.json': "JSON output";
     readonly 'help.option.group.impact.target': "Symbol or file name to analyze";

package/dist/cli/i18n/en.js

@@ -235,10 +235,8 @@ export const en = {
     'help.option.embeddings.install.cuda': "Also download the CUDA GPU binaries (runs onnxruntime-node's NuGet postinstall; set GLOBAL_AGENT_HTTPS_PROXY behind a proxy)",
     'help.option.embeddings.install.force': 'Install into the runtime prefix even when the stack already resolves',
     'help.option.group.create.force': 'Overwrite existing group',
-    'help.option.group.sync.skipEmbeddings': 'Exact + BM25 only (no embedding fallback)',
-    'help.option.group.sync.exactOnly': 'Exact match only',
-    'help.option.group.sync.allowStale': 'Skip stale index warnings',
-    'help.option.group.sync.verbose': 'Show each cross-link detail',
+    'help.option.group.sync.exactOnly': 'Skip wildcard service matching; cross-link on exact contract-id match only (manifest links still apply)',
+    'help.option.group.sync.verbose': 'Show additional sync diagnostics',
     'help.option.status.json': 'Emit machine-readable index and analyzer provenance',
     'help.option.json': 'JSON output',
     'help.option.group.impact.target': 'Symbol or file name to analyze',

package/dist/cli/i18n/resources.d.ts

@@ -234,10 +234,8 @@ export declare const cliResources: {
         readonly 'help.option.embeddings.install.cuda': "Also download the CUDA GPU binaries (runs onnxruntime-node's NuGet postinstall; set GLOBAL_AGENT_HTTPS_PROXY behind a proxy)";
         readonly 'help.option.embeddings.install.force': "Install into the runtime prefix even when the stack already resolves";
         readonly 'help.option.group.create.force': "Overwrite existing group";
-        readonly 'help.option.group.sync.skipEmbeddings': "Exact + BM25 only (no embedding fallback)";
-        readonly 'help.option.group.sync.exactOnly': "Exact match only";
-        readonly 'help.option.group.sync.allowStale': "Skip stale index warnings";
-        readonly 'help.option.group.sync.verbose': "Show each cross-link detail";
+        readonly 'help.option.group.sync.exactOnly': "Skip wildcard service matching; cross-link on exact contract-id match only (manifest links still apply)";
+        readonly 'help.option.group.sync.verbose': "Show additional sync diagnostics";
         readonly 'help.option.status.json': "Emit machine-readable index and analyzer provenance";
         readonly 'help.option.json': "JSON output";
         readonly 'help.option.group.impact.target': "Symbol or file name to analyze";
@@ -490,9 +488,7 @@ export declare const cliResources: {
         'help.option.embeddings.install.cuda': string;
         'help.option.embeddings.install.force': string;
         'help.option.group.create.force': string;
-        'help.option.group.sync.skipEmbeddings': string;
         'help.option.group.sync.exactOnly': string;
-        'help.option.group.sync.allowStale': string;
         'help.option.group.sync.verbose': string;
         'help.option.status.json': string;
         'help.option.json': string;

package/dist/cli/i18n/zh-CN.d.ts

@@ -233,9 +233,7 @@ export declare const zhCN: {
     'help.option.embeddings.install.cuda': string;
     'help.option.embeddings.install.force': string;
     'help.option.group.create.force': string;
-    'help.option.group.sync.skipEmbeddings': string;
     'help.option.group.sync.exactOnly': string;
-    'help.option.group.sync.allowStale': string;
     'help.option.group.sync.verbose': string;
     'help.option.status.json': string;
     'help.option.json': string;

package/dist/cli/i18n/zh-CN.js

@@ -233,10 +233,8 @@ export const zhCN = {
     'help.option.embeddings.install.cuda': '同时下载 CUDA GPU 二进制文件（运行 onnxruntime-node 的 NuGet postinstall；代理后请设置 GLOBAL_AGENT_HTTPS_PROXY）',
     'help.option.embeddings.install.force': '即使嵌入组件已可解析，也强制安装到运行时目录',
     'help.option.group.create.force': '覆盖现有仓库组',
-    'help.option.group.sync.skipEmbeddings': '仅使用 exact + BM25（不使用嵌入回退）',
-    'help.option.group.sync.exactOnly': '仅精确匹配',
-    'help.option.group.sync.allowStale': '跳过过期索引警告',
-    'help.option.group.sync.verbose': '显示每条跨仓库链接详情',
+    'help.option.group.sync.exactOnly': '跳过通配符服务匹配，仅按契约 ID 精确匹配建立跨仓链接（清单声明的链接仍然生效）',
+    'help.option.group.sync.verbose': '显示额外的同步诊断信息',
     'help.option.status.json': '输出机器可读的索引和分析器来源信息',
     'help.option.json': 'JSON 输出',
     'help.option.group.impact.target': '要分析的符号或文件名',

package/dist/config/ignore-service.js

@@ -53,13 +53,33 @@ const DEFAULT_IGNORE_LIST = new Set([
     'obj',
     'target', // Java/Rust
     '.next',
+    // `.next` is Next.js's build CACHE; `_next` is the EMITTED output, and the two
+    // are different directories. A Capacitor/Cordova shell copies the emitted
+    // bundle to `<platform>/app/src/main/assets/public/_next/static/…`, where none
+    // of the path segments hit this list — so a mobile-wrapped Next.js app had its
+    // shipped bundle indexed as source, and every Route node it produced pointed at
+    // a webpack chunk rather than code anyone wrote (#3007).
+    //
+    // The name is deliberately unanchored. No `<web-root>/_next` form matches a
+    // root-level `_next/static/…`, which is the shape the reported repo has, so
+    // anchoring it would miss the case it was added for. The accepted cost is a
+    // hand-written directory literally named `_next`; recover one with a bare
+    // `!_next/` line in `.gitnexusignore`.
+    '_next',
     '.nuxt',
     '.output',
     '.vercel',
     '.netlify',
     '.serverless',
     '_build',
-    'public/build',
+    // `'public/build'` used to sit here. This set is tested one path SEGMENT at a
+    // time, and `isHardcodedIgnoredDirectory(name)` takes a bare directory name,
+    // so a slash-containing member could never match either — it was inert. Its
+    // paths were never unignored though: bare `'build'` above already prunes
+    // `public/build/**`, so removing the entry changes no behavior (#3007).
+    // `test/unit/ignore-build-output.test.ts` keeps the next slash-bearing entry
+    // in this set — or in IGNORED_FILES, ROOT_ARTIFACT_DIRECTORIES or
+    // IGNORED_EXTENSIONS — from dying the same way.
     '.parcel-cache',
     '.turbo',
     '.svelte-kit',
@@ -87,7 +107,6 @@ const DEFAULT_IGNORE_LIST = new Set([
     // remains covered by .gitignore/.gitnexusignore and the unambiguous names.
     'monaco-workers', // Monaco editor web-worker bundles generated for browser runtime
     '.terraform',
-    '.serverless',
     // Documentation (optional - might want to keep)
     // 'docs',
     // 'documentation',

package/dist/core/group/bridge-db.d.ts

@@ -1,5 +1,5 @@
 import type { LbugValue } from '@ladybugdb/core';
-import type { BridgeHandle, BridgeMeta, StoredContract, CrossLink, RepoSnapshot } from './types.js';
+import type { BridgeHandle, BridgeMeta, StoredContract, CrossLink, RepoSnapshot, MatchType } from './types.js';
 /**
  * Serialize an operation on a cached handle's per-handle FIFO chain. Mirrors the
  * promise-chain mechanic of `lbug/conn-lock.ts` (install a fresh unresolved
@@ -222,6 +222,29 @@ export declare function refreshPreservedBridgeMeta(groupDir: string, diagnostics
     missingRepos: string[];
     unreadableRepos: string[];
 }): Promise<PreservedBridgeMetaOutcome>;
+/**
+ * Withdraw the bridge's claim to be complete, without touching the database.
+ *
+ * The one path this exists for: `contracts.json` committed, then the bridge
+ * replacement failed. The old database is still physically usable and still
+ * answers queries, but it now describes an EARLIER sync than the canonical
+ * registry beside it — so `group_contracts` can report a narrowed or advanced
+ * contract set while `group_impact` traverses the old graph and calls its
+ * answer complete. Two public surfaces, contradictory epistemic claims, from
+ * one sync.
+ *
+ * Setting `provenanceUnknown` is the smallest thing that makes that safe:
+ * `bridgeMetaMatchesFile` gives it highest precedence and refuses to vouch for
+ * the pair, so every cross-repo answer downgrades to a floor until a sync
+ * succeeds. Deliberately NOT a re-stamp — the metadata still describes the
+ * database it was written for, and claiming otherwise is the mis-pairing the
+ * preserve path is careful to avoid. Deliberately not a delete either: the
+ * previous graph is better than nothing as long as nobody calls it complete.
+ *
+ * Best-effort by construction. It runs inside a failure handler, so a throw
+ * here would replace a reported bridge failure with an unrelated one.
+ */
+export declare function markBridgeProvenanceUnknown(groupDir: string): Promise<boolean>;
 export interface WriteBridgeInput {
     contracts: StoredContract[];
     crossLinks: CrossLink[];
@@ -243,6 +266,13 @@ export interface WriteBridgeInput {
      * contract those repos own.
      */
     unreadableRepos?: string[];
+    /**
+     * Matching stages the sync was asked to skip. Recorded here for the same
+     * reason `unreadableRepos` is: a later cross-repo query reads this bridge
+     * with no access to the run that built it, and a graph narrowed by request
+     * looks exactly like a complete one.
+     */
+    suppressedMatchStages?: MatchType[];
 }
 /**
  * Non-fatal issues encountered during writeBridge. Callers can log these to

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

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { createHash } from 'node:crypto';
 import lbug from '@ladybugdb/core';
 import { BRIDGE_SCHEMA_QUERIES, BRIDGE_SCHEMA_VERSION } from './bridge-schema.js';
-import { recordedRepoList } from './completeness.js';
+import { recordedMatchStages, recordedRepoList } from './completeness.js';
 import { closeLbugConnection, openLbugConnection, } from '../lbug/lbug-config.js';
 import { dedupeContracts, dedupeCrossLinks } from './normalization.js';
 import { withGroupSyncLock } from './group-lock.js';
@@ -518,7 +518,15 @@ export async function closeBridgeDb(handle) {
 /*  writeBridgeMeta / readBridgeMeta                                  */
 /* ------------------------------------------------------------------ */
 export async function writeBridgeMeta(groupDir, meta) {
-    await writeFileAtomic(path.join(groupDir, 'meta.json'), JSON.stringify(meta, null, 2));
+    // Strip the reader-only fields HERE rather than at each writer. `readBridgeMeta`
+    // sets both on what it returns, so any caller that reads-modifies-writes would
+    // round-trip them to disk — and `pairedWithDatabase` is the poisonous one:
+    // persisted, it tells every future reader the pair was verified when nothing
+    // verified it. That rule used to live in the body of the only such caller,
+    // which held exactly as long as there was one. There are now three writers and
+    // two of them read first. Enforced at the boundary, no writer can get it wrong.
+    const { repoListsUnreadable: _reader1, pairedWithDatabase: _reader2, ...persisted } = meta;
+    await writeFileAtomic(path.join(groupDir, 'meta.json'), JSON.stringify(persisted, null, 2));
 }
 /**
  * Does `meta` still describe the `bridge.lbug` sitting next to it?
@@ -697,6 +705,12 @@ export async function readBridgeMeta(groupDir) {
         meta.unreadableRepos = unreadableRepos;
     else
         delete meta.unreadableRepos;
+    // Same absent-vs-empty rule, through the one shared reader.
+    const suppressed = recordedMatchStages(raw.suppressedMatchStages);
+    if (suppressed)
+        meta.suppressedMatchStages = suppressed;
+    else
+        delete meta.suppressedMatchStages;
     if (repoListsUnreadable)
         meta.repoListsUnreadable = true;
     return meta;
@@ -754,7 +768,14 @@ async function fileExists(filePath) {
  * section ever appears, it needs the same treatment `writeBridge` got — a
  * wrapper, not a lock moved down here.
  */
-export async function refreshPreservedBridgeMeta(groupDir, diagnostics) {
+export async function refreshPreservedBridgeMeta(groupDir, 
+// Deliberately NOT `suppressedMatchStages`. This path preserves an EARLIER
+// sync's database, so stamping it with this run's request would claim the
+// untouched bridge was built with a flag it never saw. The registry's own
+// preserve write (`{ ...prior, missingRepos, unreadableRepos }`) omits it for
+// exactly this reason, and the two artifacts have to agree about which run
+// they describe.
+diagnostics) {
     const dbPath = path.join(groupDir, 'bridge.lbug');
     const [metaOnDisk, dbOnDisk] = await Promise.all([
         fileExists(path.join(groupDir, 'meta.json')),
@@ -771,10 +792,8 @@ export async function refreshPreservedBridgeMeta(groupDir, diagnostics) {
     const refreshed = { ...existing, ...diagnostics };
     // NEVER PERSISTED (see `BridgeMeta`): both are things a READER computes ABOUT
     // a file, and this is the first code in the repo that reads metadata and
-    // writes it back. `pairedWithDatabase` is the poisonous one — persisted, it
-    // would tell every future reader that the pair had been verified.
-    delete refreshed.repoListsUnreadable;
-    delete refreshed.pairedWithDatabase;
+    // writes it back. The strip itself now lives in `writeBridgeMeta`, so every
+    // writer inherits it rather than each remembering.
     if (paired) {
         const stat = await fsp.stat(dbPath).catch(() => null);
         if (stat) {
@@ -791,6 +810,40 @@ export async function refreshPreservedBridgeMeta(groupDir, diagnostics) {
     await writeBridgeMeta(groupDir, refreshed);
     return 'provenance-unknown';
 }
+/**
+ * Withdraw the bridge's claim to be complete, without touching the database.
+ *
+ * The one path this exists for: `contracts.json` committed, then the bridge
+ * replacement failed. The old database is still physically usable and still
+ * answers queries, but it now describes an EARLIER sync than the canonical
+ * registry beside it — so `group_contracts` can report a narrowed or advanced
+ * contract set while `group_impact` traverses the old graph and calls its
+ * answer complete. Two public surfaces, contradictory epistemic claims, from
+ * one sync.
+ *
+ * Setting `provenanceUnknown` is the smallest thing that makes that safe:
+ * `bridgeMetaMatchesFile` gives it highest precedence and refuses to vouch for
+ * the pair, so every cross-repo answer downgrades to a floor until a sync
+ * succeeds. Deliberately NOT a re-stamp — the metadata still describes the
+ * database it was written for, and claiming otherwise is the mis-pairing the
+ * preserve path is careful to avoid. Deliberately not a delete either: the
+ * previous graph is better than nothing as long as nobody calls it complete.
+ *
+ * Best-effort by construction. It runs inside a failure handler, so a throw
+ * here would replace a reported bridge failure with an unrelated one.
+ */
+export async function markBridgeProvenanceUnknown(groupDir) {
+    try {
+        const existing = await readBridgeMeta(groupDir);
+        if (existing.version === 0)
+            return false;
+        await writeBridgeMeta(groupDir, { ...existing, provenanceUnknown: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 const MAX_SAMPLE_ERRORS = 10;
 function errMessage(err) {
     if (err instanceof Error)
@@ -1085,6 +1138,9 @@ export async function writeBridgeUnlocked(groupDir, input) {
             // different claim from a bridge that never recorded the field. Omitted
             // only when the caller passed nothing to record.
             ...(input.unreadableRepos ? { unreadableRepos: input.unreadableRepos } : {}),
+            ...(input.suppressedMatchStages
+                ? { suppressedMatchStages: input.suppressedMatchStages }
+                : {}),
         });
         return report;
     }

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

@@ -13,7 +13,7 @@
  * Nothing here imports anything but types. Keep it that way: the moment this
  * file gains a runtime import, every consumer pays for it again.
  */
-import type { GroupImpactTruncationReason } from './types.js';
+import type { GroupImpactTruncationReason, MatchType } from './types.js';
 /**
  * A union rather than `Pick<GroupImpactResult, ...>` so the two states are
  * distinguishable by their `truncated` discriminant: a caller that folds these
@@ -58,6 +58,12 @@ export interface CrossRepoCompletenessInput {
      */
     unreadableRepos?: readonly string[];
     missingRepos?: readonly string[];
+    /**
+     * Matching stages the sync was asked to skip. Absent or empty means it
+     * suppressed none; a populated list makes the answer a floor for a reason
+     * that is neither a runtime limit nor an unreadable repo.
+     */
+    suppressedMatchStages?: readonly string[];
     /** Computed by the caller; see `bridgeProvenanceUnknown` for the bridge one. */
     provenanceUnknown: boolean;
     /**
@@ -80,6 +86,18 @@ export type CrossRepoCompleteness = TruncationFields & {
      */
     incompleteRepos: string[];
 };
+/**
+ * Read a persisted `suppressedMatchStages` list.
+ *
+ * Sibling of `recordedRepoList` and here for the same stated reason: it had
+ * lived in two files verbatim, so tightening one would silently leave the other.
+ * All-or-nothing like its sibling — a stale member (this repo has already
+ * retired `'bm25'` and `'embedding'`) makes the whole list unreadable rather
+ * than filtering down to `[]`, which on this field would mean "measured,
+ * nothing suppressed": a clean answer manufactured from a value we could not
+ * read.
+ */
+export declare function recordedMatchStages(value: unknown): MatchType[] | undefined;
 /**
  * The ONE computation of "is this cross-repo answer complete?" (KTD10).
  *

package/dist/core/group/completeness.js

@@ -16,6 +16,23 @@ reasonIfTruncated = 'partial') {
         return { truncated: false };
     return { truncated: true, truncationReason: reasonIfTruncated, riskEpistemic: 'lower-bound' };
 }
+/**
+ * Read a persisted `suppressedMatchStages` list.
+ *
+ * Sibling of `recordedRepoList` and here for the same stated reason: it had
+ * lived in two files verbatim, so tightening one would silently leave the other.
+ * All-or-nothing like its sibling — a stale member (this repo has already
+ * retired `'bm25'` and `'embedding'`) makes the whole list unreadable rather
+ * than filtering down to `[]`, which on this field would mean "measured,
+ * nothing suppressed": a clean answer manufactured from a value we could not
+ * read.
+ */
+export function recordedMatchStages(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const known = ['exact', 'manifest', 'wildcard'];
+    return value.every((v) => known.includes(v)) ? value : undefined;
+}
 /**
  * The ONE computation of "is this cross-repo answer complete?" (KTD10).
  *
@@ -34,8 +51,14 @@ export function crossRepoCompleteness(input) {
     const incompleteRepos = [
         ...new Set([...(input.unreadableRepos ?? []), ...(input.missingRepos ?? [])]),
     ].filter((repoPath) => input.inScope(repoPath));
+    // An unreadable or unaccounted repo outranks a suppressed stage: it is the
+    // more serious structural gap and its remedy (repair the repo, re-sync) has
+    // to be the one reported. A suppressed stage only decides the reason when
+    // the repo side is otherwise clean.
+    const suppressed = (input.suppressedMatchStages ?? []).length > 0;
+    const repoSideIncomplete = input.provenanceUnknown || incompleteRepos.length > 0;
     return {
-        ...truncationFields(input.provenanceUnknown || incompleteRepos.length > 0, 'incomplete-sync'),
+        ...truncationFields(repoSideIncomplete || suppressed, repoSideIncomplete ? 'incomplete-sync' : 'suppressed-stage'),
         incompleteRepos,
     };
 }

package/dist/core/group/config-parser.js

@@ -25,15 +25,10 @@ const DEFAULT_DETECT = {
     grpc: true,
     thrift: true,
     topics: true,
-    shared_libs: true,
-    embedding_fallback: true,
     includes: false,
     workspace_deps: false,
 };
 const DEFAULT_MATCHING = {
-    bm25_threshold: 0.7,
-    embedding_threshold: 0.65,
-    max_candidates_per_step: 3,
     exclude_links_paths: [],
     exclude_links_param_only_paths: false,
 };

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

@@ -696,6 +696,7 @@ export async function runGroupImpact(deps, params) {
     const bridge = crossRepoCompleteness({
         unreadableRepos: bridgePrep.meta.unreadableRepos,
         missingRepos: bridgePrep.meta.missingRepos,
+        suppressedMatchStages: bridgePrep.meta.suppressedMatchStages,
         provenanceUnknown,
         inScope: (candidate) => repoInSubgroup(candidate, subgroup) || repoInSubgroup(candidate, repoPath, true),
     });
@@ -716,13 +717,21 @@ export async function runGroupImpact(deps, params) {
         // and under-reporting a blast radius is the unsafe direction (an agent told
         // LOW proceeds; told CRITICAL it stops). Marking the floor keeps the
         // warning intact while making the incompleteness legible.
-        // Runtime limits first — they are what the caller can retry. 'incomplete-sync'
-        // is the remaining cause once nothing was merely cut short, and its remedy is
-        // a different one: re-run `gitnexus group sync`, not the query. Computed
-        // inline because `truncationFields` reads the reason ONLY on the truncated
-        // branch — naming it in a variable invited reading it on the complete path,
-        // where it would say 'incomplete-sync' about a complete result.
-        ...truncationFields(truncated, fanoutTimedOut ? 'timeout' : runtimeTruncated ? 'partial' : 'incomplete-sync'),
+        // Runtime limits first — they are what the caller can retry. Past those, the
+        // BRIDGE's own reason wins: it already distinguished an unreadable repo
+        // ('incomplete-sync', remedy: re-sync) from a stage the sync was asked to
+        // skip ('suppressed-stage', remedy: re-sync WITHOUT the flag). Hardcoding
+        // the fallback here overrode that and told every caller to repair a repo
+        // that read fine — and made the second value unreachable from this surface
+        // while the tool description promised it. `cross-trace.ts` re-spreads the
+        // bridge's fields for the same reason.
+        ...truncationFields(truncated, fanoutTimedOut
+            ? 'timeout'
+            : runtimeTruncated
+                ? 'partial'
+                : bridge.truncated
+                    ? bridge.truncationReason
+                    : 'incomplete-sync'),
         truncatedRepos: [...new Set([...truncatedRepos, ...bridge.incompleteRepos])],
         summary: {
             direct: localSum.direct ?? 0,

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

@@ -102,6 +102,7 @@ function bridgeCompletenessFor(meta, inScope) {
     return crossRepoCompleteness({
         unreadableRepos: meta.unreadableRepos,
         missingRepos: meta.missingRepos,
+        suppressedMatchStages: meta.suppressedMatchStages,
         provenanceUnknown: bridgeProvenanceUnknown(meta),
         inScope,
     });