gitnexus 1.6.10-rc.99 → 1.6.10

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

@@ -1,5 +1,5 @@
 export type ContractType = 'http' | 'grpc' | 'thrift' | 'topic' | 'lib' | 'custom' | 'include';
-export type MatchType = 'exact' | 'manifest' | 'wildcard' | 'bm25' | 'embedding';
+export type MatchType = 'exact' | 'manifest' | 'wildcard';
 export type ContractRole = 'provider' | 'consumer';
 export interface GroupConfig {
     version: number;
@@ -23,15 +23,10 @@ export interface DetectConfig {
     grpc: boolean;
     thrift: boolean;
     topics: boolean;
-    shared_libs: boolean;
-    embedding_fallback: boolean;
     includes: boolean;
     workspace_deps: boolean;
 }
 export interface MatchingConfig {
-    bm25_threshold: number;
-    embedding_threshold: number;
-    max_candidates_per_step: number;
     /**
      * HTTP paths to exclude from cross-link matching. Contracts at these paths
      * are still extracted and visible in the registry, but they don't produce
@@ -90,7 +85,34 @@ export interface ContractRegistry {
     version: number;
     generatedAt: string;
     repoSnapshots: Record<string, RepoSnapshot>;
+    /** Configured repos with no entry in the registry. */
     missingRepos: string[];
+    /**
+     * Configured repos that ARE registered but that this sync could not extract
+     * from — the index would not open (version skew, lock, corruption), or an
+     * extractor threw partway through. The two are one bucket because the
+     * consequence is one thing: NONE of that repo's contracts are in this
+     * registry. Distinct from `missingRepos`, which is "no entry in the
+     * registry at all" and needs a different answer from the operator.
+     *
+     * Optional so a registry written before this field existed still parses —
+     * absent means "not recorded", not "none".
+     */
+    unreadableRepos?: string[];
+    /**
+     * Matching stages this sync was ASKED to skip, so a later reader can tell a
+     * short cross-link list from a complete one. `--exact-only` / `exactOnly`
+     * suppresses the wildcard stage, and the registry it writes is otherwise
+     * indistinguishable from one where that stage ran and matched nothing.
+     *
+     * Same tri-state as `unreadableRepos` and for the same reason: absent means
+     * "not recorded" (written before this field existed), `[]` means "measured,
+     * nothing was suppressed", and a populated list names the stages. Distinct
+     * from `truncated` / `truncationReason`, which report limits this run hit by
+     * accident — a suppressed stage is a deliberate request, and its remedy is
+     * "re-sync without exactOnly", not "fix the unreadable repo".
+     */
+    suppressedMatchStages?: MatchType[];
     contracts: StoredContract[];
     crossLinks: CrossLink[];
 }
@@ -104,8 +126,30 @@ export interface RepoHandle {
     repoPath: string;
     storagePath: string;
 }
-/** Why local impact or fan-out stopped early (e.g. wall-clock budget exhausted). */
-export type GroupImpactTruncationReason = 'timeout' | 'partial';
+/**
+ * Why local impact or fan-out stopped early (e.g. wall-clock budget exhausted).
+ *
+ * `'timeout'` and `'partial'` are runtime limits — the same query can succeed on
+ * a retry. `'incomplete-sync'` is structural: the bridge itself was built from a
+ * sync that could not read every configured repo, so those repos' contracts are
+ * absent from every query against it until `gitnexus group sync` succeeds.
+ * `'suppressed-stage'` is structural too but has its own remedy: the sync was
+ * ASKED to skip a matching stage (`--exact-only`), so cross-links that stage
+ * would have found are absent by request. Retrying returns the same floor, and
+ * so does re-running the sync — the fix is to re-run it WITHOUT the flag. Kept a
+ * separate member rather than folded into `'incomplete-sync'` precisely because
+ * that remedy differs; telling an agent to repair a repo it read fine is the
+ * failure this distinction exists to prevent.
+ *
+ * A runtime array rather than a bare type union: every value here has to be
+ * explained on the agent-facing surface that returns it, and only an enumerable
+ * list lets a guard test assert that. A test that hand-lists the members passes
+ * forever once a fourth is added — which is the exact drift the guard exists to
+ * catch, so the list an agent is promised and the list the code can emit have
+ * to come from the same place.
+ */
+export declare const GROUP_IMPACT_TRUNCATION_REASONS: readonly ["timeout", "partial", "incomplete-sync", "suppressed-stage"];
+export type GroupImpactTruncationReason = (typeof GROUP_IMPACT_TRUNCATION_REASONS)[number];
 export interface GroupImpactResult {
     local: unknown;
     group: string;
@@ -120,6 +164,18 @@ export interface GroupImpactResult {
         cross_repo_hits: number;
     };
     risk: string;
+    /**
+     * `'lower-bound'` when the fan-out was cut short, so `risk` is a FLOOR, not a
+     * verdict. Same vocabulary as single-repo `impact`'s `epistemic` field.
+     *
+     * `mergeRisk` is monotone increasing in the number of traversed crossings, so
+     * dropping a crossing can only move the reported risk DOWN — a fully
+     * truncated fan-out returns bare `localRisk`, making a symbol whose blast
+     * radius crosses a repo boundary indistinguishable from one with no
+     * cross-repo consumers. Absent this marker a truncated run emits a
+     * confident-looking `risk` byte-identical to a complete one.
+     */
+    riskEpistemic?: 'lower-bound';
     /**
      * Milliseconds budget applied to the **Phase 1 local impact** leg (`safeLocalImpact`).
      * If the walk hits this wall first, expect `truncationReason: 'timeout'` and a partial `local` payload.
@@ -160,6 +216,12 @@ export interface CrossRepoImpact {
     };
     by_depth: Record<string, unknown[]>;
     affected_processes: string[];
+    /**
+     * Present when the bridge proves a repository boundary but the far endpoint
+     * has no graph symbol, so local fan-out cannot be attempted. Omitted for
+     * completed fan-out to preserve the existing serialized result shape.
+     */
+    fanout_status?: 'not_attempted';
 }
 export interface OutOfScopeLink {
     from: string;
@@ -184,5 +246,118 @@ export interface BridgeHandle {
 export interface BridgeMeta {
     version: number;
     generatedAt: string;
+    /**
+     * Size and mtime of the `bridge.lbug` this metadata was written for, so a
+     * reader can tell whether the two still belong together.
+     *
+     * `writeBridge` replaces the database and writes this file as two operations;
+     * a sync that stops between them leaves the PREVIOUS sync's metadata beside a
+     * new database, and `runGroupImpact` reads completeness from that metadata.
+     * Stamping the pair is what lets `bridgeMetaMatchesFile` reject the mismatch
+     * without anything having to be deleted — deleting the old metadata up front
+     * would lose it permanently on a swap that fails with the old database still
+     * in place, which is a normal Windows outcome when a read-only handle is held.
+     *
+     * Optional: metadata written before this existed carries no stamp. Such a
+     * file is not waved through — `bridgeMetaMatchesFile` falls back to comparing
+     * the two files' modification times, since a successful write orders the
+     * database rename before the metadata write and a database NEWER than the
+     * metadata beside it therefore cannot be the one it describes.
+     *
+     * That fallback proves WRITE ORDER, not provenance, and is wrong in both
+     * directions — a non-monotonic clock can make a mis-paired set read as
+     * ordered, and any copy or restore that rewrites the database's times after
+     * the metadata's demotes an intact legacy pair to a lower bound until the
+     * next sync re-stamps it. A stamped pair never reaches that fallback, which
+     * is the reason to prefer stamping over widening the heuristic. Both
+     * directions are spelled out at `bridgeMetaMatchesFile`.
+     */
+    bridgeSize?: number;
+    bridgeMtimeMs?: number;
+    /**
+     * Reader-side only: true when `meta.json` parsed but one of its repo lists
+     * held a value that was not a list of repo paths.
+     *
+     * NEVER PERSISTED. `readBridgeMeta` sets it to describe what it found in the
+     * file; `writeBridgeMeta`'s only caller builds a fresh literal, so it cannot
+     * round-trip back to disk. It lives on this interface rather than on a
+     * reader-only subtype so that `readBridgeMeta` keeps the exact signature
+     * every caller already compiles against.
+     *
+     * The unusable value is dropped rather than normalized, so `missingRepos: []`
+     * on such a result is inert filler — this flag, not the empty list, is what
+     * says the bridge's provenance is unknown.
+     */
+    repoListsUnreadable?: boolean;
+    /**
+     * Reader-side only: did this metadata pair with the `bridge.lbug` beside it,
+     * measured BEFORE anything opened that database?
+     *
+     * NEVER PERSISTED, for the same reason as `repoListsUnreadable`.
+     *
+     * The measurement has to happen before the open, and the answer has to be
+     * carried rather than recomputed. `runGroupImpact` and `runGroupTrace` open
+     * the bridge and only then ask about provenance, so a platform where a
+     * read-only open advances the database's mtime would fail every unstamped
+     * pair the moment it was read — turning back-compat for pre-stamp bridges
+     * into a repo-wide "everything is a lower bound". Whether any given
+     * LadybugDB build and OS does that is not something a reader should have to
+     * know, and it cannot be observed on Windows, where the in-process
+     * write→read reopen this would need is a documented limitation. Ordering the
+     * check ahead of the open makes the question moot on every platform instead
+     * of true on the ones that happen to be testable.
+     */
+    pairedWithDatabase?: boolean;
+    /**
+     * PERSISTED, unlike the two fields above: the writer of this metadata could
+     * not establish that it describes the `bridge.lbug` beside it, and no reader
+     * may conclude otherwise from the files alone.
+     *
+     * Written by `refreshPreservedBridgeMeta` — the preserve path in `syncGroup`,
+     * which refreshes the diagnostic lists of a bridge it deliberately does NOT
+     * rebuild. That refresh rewrites `meta.json` ATOMICALLY, so this file's mtime
+     * becomes now while the database's stays old; and "metadata newer than the
+     * database beside it" is exactly the write order that
+     * `unstampedMetaPairsByWriteOrder` accepts. A refresh that simply carried the
+     * old fields forward would therefore convert a pair that check had been
+     * REJECTING into one it waves through — laundering unknown provenance into
+     * verified provenance, which is the fail-open this whole channel exists to
+     * close.
+     *
+     * "Just don't write a stamp" is not a substitute, and is worse: an unstamped
+     * metadata file is judged on the two file times, and the refresh has already
+     * moved them into the accepting order. The verdict has to be recorded IN the
+     * file, because the write that records it is itself what destroys the
+     * evidence a reader would otherwise use.
+     *
+     * `bridgeMetaMatchesFile` rejects on this ahead of both the stamp and the
+     * write-order heuristic, so `ensureBridgeReady` answers
+     * `pairedWithDatabase: false` and `bridgeProvenanceUnknown` reports the
+     * cross-repo answer as a lower bound. That is the ONE enforcement point; do
+     * not add a second reader for this field.
+     *
+     * Self-clearing: a successful `writeBridge` builds fresh metadata from a
+     * literal and never sets it, so the next good sync retires the marker without
+     * anything having to delete it.
+     */
+    provenanceUnknown?: boolean;
     missingRepos: string[];
+    /**
+     * Configured repos the sync that produced this bridge could not extract from
+     * (see `ContractRegistry.unreadableRepos`). Their contracts and every
+     * cross-link touching them are absent from `bridge.lbug`, so a cross-repo
+     * impact query against this bridge is a lower bound, not a verdict —
+     * `runGroupImpact` folds a non-empty value into its truncation fields for
+     * exactly that reason.
+     * Optional: a bridge written before this field existed does not record it.
+     */
+    unreadableRepos?: string[];
+    /**
+     * Matching stages the sync that built this bridge was asked to skip.
+     * PERSISTED, like `unreadableRepos` and unlike `repoListsUnreadable` — a
+     * later `group_impact` or `trace` reads this bridge with no access to the run
+     * that produced it, and a narrowed graph is otherwise indistinguishable from
+     * a complete one. Same tri-state: absent is "not recorded".
+     */
+    suppressedMatchStages?: MatchType[];
 }

package/dist/core/group/types.js

@@ -1 +1,28 @@
-export {};
+/**
+ * Why local impact or fan-out stopped early (e.g. wall-clock budget exhausted).
+ *
+ * `'timeout'` and `'partial'` are runtime limits — the same query can succeed on
+ * a retry. `'incomplete-sync'` is structural: the bridge itself was built from a
+ * sync that could not read every configured repo, so those repos' contracts are
+ * absent from every query against it until `gitnexus group sync` succeeds.
+ * `'suppressed-stage'` is structural too but has its own remedy: the sync was
+ * ASKED to skip a matching stage (`--exact-only`), so cross-links that stage
+ * would have found are absent by request. Retrying returns the same floor, and
+ * so does re-running the sync — the fix is to re-run it WITHOUT the flag. Kept a
+ * separate member rather than folded into `'incomplete-sync'` precisely because
+ * that remedy differs; telling an agent to repair a repo it read fine is the
+ * failure this distinction exists to prevent.
+ *
+ * A runtime array rather than a bare type union: every value here has to be
+ * explained on the agent-facing surface that returns it, and only an enumerable
+ * list lets a guard test assert that. A test that hand-lists the members passes
+ * forever once a fourth is added — which is the exact drift the guard exists to
+ * catch, so the list an agent is promised and the list the code can emit have
+ * to come from the same place.
+ */
+export const GROUP_IMPACT_TRUNCATION_REASONS = [
+    'timeout',
+    'partial',
+    'incomplete-sync',
+    'suppressed-stage',
+];

package/dist/core/incremental/subgraph-extract.d.ts

@@ -6,8 +6,8 @@
  * replaced, produce a smaller KnowledgeGraph that contains:
  *
  *   - Every node whose `properties.filePath` is in `toWriteSet`.
- *   - Every graph-wide node (Community, Process) — these are regenerated
- *     each run by the communities/processes phases and must be fully
+ *   - Every graph-wide node (Community, Process, and Spring metadata
+ *     placeholders) — these are regenerated each run and must be fully
  *     rewritten.
  *   - Every relationship where AT LEAST ONE endpoint is in the writable
  *     set above. Relationships entirely between unchanged-file nodes
@@ -51,10 +51,13 @@ import type { KnowledgeGraph } from '../graph/types.js';
 export declare const extractChangedSubgraph: (fullGraph: KnowledgeGraph, toWriteSet: ReadonlySet<string>) => KnowledgeGraph;
 /**
  * Public — derive the EFFECTIVE write-set: `toWriteSet` expanded by one
- * hop along every edge in the new graph that crosses the writable
- * boundary (one endpoint in a writable file, the other in an unchanged
- * file). The unchanged-side file is pulled in so its stale rows are
- * deleted + rewritten in lockstep with the changed side.
+ * hop along every file-owned edge in the new graph that crosses the
+ * writable boundary (one endpoint in a writable file, the other in an
+ * unchanged file). Graph-wide relationships are excluded: their owner
+ * phase delete-alls and re-extracts them independently, so following them
+ * here would turn high-fan-out metadata into a near-full-repository write.
+ * For ordinary edges, the unchanged-side file is pulled in so its stale
+ * rows are deleted + rewritten in lockstep with the changed side.
  *
  * Single pass over the edge list. Does NOT mutate `toWriteSet`. The
  * orchestrator MUST feed the returned set to both `deleteNodesForFiles`

package/dist/core/incremental/subgraph-extract.js

@@ -6,8 +6,8 @@
  * replaced, produce a smaller KnowledgeGraph that contains:
  *
  *   - Every node whose `properties.filePath` is in `toWriteSet`.
- *   - Every graph-wide node (Community, Process) — these are regenerated
- *     each run by the communities/processes phases and must be fully
+ *   - Every graph-wide node (Community, Process, and Spring metadata
+ *     placeholders) — these are regenerated each run and must be fully
  *     rewritten.
  *   - Every relationship where AT LEAST ONE endpoint is in the writable
  *     set above. Relationships entirely between unchanged-file nodes
@@ -48,7 +48,12 @@
  * IMPORTS from the pre-pipeline DB) covers that case instead.
  */
 import { createKnowledgeGraph } from '../graph/graph.js';
-const isGraphWide = (label) => label === 'Community' || label === 'Process';
+import { isSpringAutoConfigurationDeclaration, isSpringAutoConfigurationSyntheticClass, } from '../ingestion/frameworks/spring/auto-configuration.js';
+import { isSpringAopEvidenceNode } from '../ingestion/frameworks/spring/aop.js';
+const isGraphWideNode = (node) => node.label === 'Community' ||
+    node.label === 'Process' ||
+    isSpringAopEvidenceNode(node) ||
+    isSpringAutoConfigurationSyntheticClass(node);
 /**
  * Relationship types whose VALIDITY is a whole-program property, not a
  * function of their endpoints' files (#2084 M4 U6). `TAINT_PATH` (cross-
@@ -76,7 +81,20 @@ const isGraphWide = (label) => label === 'Community' || label === 'Process';
 // analyze, and the `incrementalInProgress` dirty flag (saved before any
 // delete) forces a full rebuild on the next run. Temporary absence is
 // possible; duplicates are not.
-const isGraphWideRelType = (type) => type === 'TAINT_PATH' || type === 'CALL_SUMMARY' || type === 'INJECTS';
+//
+// Spring auto-configuration DECLARES edges (#2415) are also recomputed from
+// repository-wide metadata. A third-file class addition/removal can retarget
+// an unchanged declaration, so they need the same global re-extract contract.
+// DECLARES itself is generic, however: only the two Spring-owned reasons are
+// graph-wide, leaving future metadata systems under their own lifecycle.
+const isGraphWideRelationship = (relationship) => relationship.type === 'TAINT_PATH' ||
+    relationship.type === 'CALL_SUMMARY' ||
+    relationship.type === 'INJECTS' ||
+    // Spring pointcut matching (#2416) is repository-wide. A third-file change
+    // can alter annotation-name visibility or the set matched by a wildcard,
+    // even when neither endpoint file changed.
+    relationship.type === 'ADVISED_BY' ||
+    isSpringAutoConfigurationDeclaration(relationship);
 /**
  * Build a Map<nodeId, filePath> for every File-bound node in the graph.
  * Graph-wide nodes (Community/Process) have no filePath and are filtered.
@@ -95,7 +113,7 @@ export const extractChangedSubgraph = (fullGraph, toWriteSet) => {
     const writableNodeIds = new Set();
     fullGraph.forEachNode((n) => {
         const filePath = n.properties?.filePath;
-        const include = (filePath && toWriteSet.has(filePath)) || isGraphWide(n.label);
+        const include = (filePath && toWriteSet.has(filePath)) || isGraphWideNode(n);
         if (include) {
             sub.addNode(n);
             writableNodeIds.add(n.id);
@@ -104,7 +122,7 @@ export const extractChangedSubgraph = (fullGraph, toWriteSet) => {
     fullGraph.forEachRelationship((r) => {
         if (writableNodeIds.has(r.sourceId) ||
             writableNodeIds.has(r.targetId) ||
-            isGraphWideRelType(r.type)) {
+            isGraphWideRelationship(r)) {
             sub.addRelationship(r);
         }
     });
@@ -112,10 +130,13 @@ export const extractChangedSubgraph = (fullGraph, toWriteSet) => {
 };
 /**
  * Public — derive the EFFECTIVE write-set: `toWriteSet` expanded by one
- * hop along every edge in the new graph that crosses the writable
- * boundary (one endpoint in a writable file, the other in an unchanged
- * file). The unchanged-side file is pulled in so its stale rows are
- * deleted + rewritten in lockstep with the changed side.
+ * hop along every file-owned edge in the new graph that crosses the
+ * writable boundary (one endpoint in a writable file, the other in an
+ * unchanged file). Graph-wide relationships are excluded: their owner
+ * phase delete-alls and re-extracts them independently, so following them
+ * here would turn high-fan-out metadata into a near-full-repository write.
+ * For ordinary edges, the unchanged-side file is pulled in so its stale
+ * rows are deleted + rewritten in lockstep with the changed side.
  *
  * Single pass over the edge list. Does NOT mutate `toWriteSet`. The
  * orchestrator MUST feed the returned set to both `deleteNodesForFiles`
@@ -126,6 +147,8 @@ export const computeEffectiveWriteSet = (fullGraph, toWriteSet) => {
     const nodeFilePaths = indexNodeFilePaths(fullGraph);
     const expanded = new Set(toWriteSet);
     fullGraph.forEachRelationship((r) => {
+        if (isGraphWideRelationship(r))
+            return;
         const sourcePath = nodeFilePaths.get(r.sourceId);
         const targetPath = nodeFilePaths.get(r.targetId);
         if (!sourcePath || !targetPath)

package/dist/core/index-freshness.d.ts

@@ -1,5 +1,80 @@
 import type { RepoMeta } from '../storage/repo-manager.js';
-export declare const INDEX_INCOMPLETE_REASONS: readonly ["incremental-in-progress", "embedding-checkpoint-pending"];
+export declare const INDEX_INCOMPLETE_REASONS: readonly ["incremental-in-progress", "embedding-checkpoint-pending", "embedding-count-unverified", "graph-write-collapsed"];
 export type IndexIncompleteReason = (typeof INDEX_INCOMPLETE_REASONS)[number];
+/**
+ * Fraction of the pipeline's relationship count that must survive into the DB
+ * before the write counts as collapsed. Deliberately generous: this detects
+ * "most of the graph did not persist" (the reported case lost ~91%), not a
+ * per-edge reconciliation.
+ */
+export declare const GRAPH_WRITE_COLLAPSE_RATIO = 0.5;
+/**
+ * Below this many relationships the ratio is meaningless — a handful of edges
+ * lost to legitimate filtering would trip it — so small repos are exempt.
+ */
+export declare const GRAPH_WRITE_COLLAPSE_MIN_EDGES = 100;
+/** Why {@link detectGraphWriteCollapse} could reach no verdict at all. */
+export type GraphWriteCollapseUnmeasurableReason = 
+/** The pipeline's own total was not a usable number (or was zero). */
+'expected-unavailable'
+/** The DB-side count could not be READ — a query that threw, no connection. */
+ | 'persisted-unreadable'
+/** Set by the CALLER: an incremental write persists only the changed
+ *  subgraph, so whole-scope counts are not comparable to it. */
+ | 'incremental-write';
+/**
+ * The three outcomes of the collapse check, kept APART because two of them used
+ * to share `undefined` and the conflation erased a stamp recording real,
+ * unrepaired edge loss.
+ *
+ * `'healthy'` is a POSITIVE all-clear — the counts were both taken and enough
+ * rows persisted — and is the only outcome that licenses clearing a previous
+ * `graph-write-collapsed` stamp. `'unmeasurable'` says the comparison never
+ * happened; the previous stamp must survive it, because nothing has repaired
+ * whatever it recorded.
+ */
+export type GraphWriteCollapseVerdict = {
+    verdict: 'collapsed';
+    expected: number;
+    persisted: number;
+} | {
+    verdict: 'healthy';
+} | {
+    verdict: 'unmeasurable';
+    reason: GraphWriteCollapseUnmeasurableReason;
+};
+/**
+ * Decide whether a finished write collapsed, comparing what the pipeline
+ * produced against what the DB hands back.
+ *
+ * A RATIO, not equality: some relationship types do not round-trip one-for-one
+ * and `--pdg` writes MORE rows into the same table, so demanding equality would
+ * fire on healthy runs. Only a collapse is a defect.
+ *
+ * FAIL-SAFE at `expected === 0`: an implementation that offloads relationships
+ * out of memory may not be able to report a total, and a false "your index is
+ * broken" is worse than a missed one. That case is `'unmeasurable'`, NOT
+ * `'healthy'` — nothing was compared, so nothing was cleared.
+ *
+ * Returns a THREE-WAY verdict rather than `{...} | undefined`. The absent value
+ * meant both "measured, fine" and "could not measure", and the caller — which
+ * decides whether to keep or erase the persisted `graph-write-collapsed` stamp —
+ * cannot tell those apart from a shared `undefined`. It guessed by write mode
+ * instead, so a full run whose structural count threw took the
+ * "no collapse ⇒ clear it" branch and deleted a stamp recording real loss.
+ */
+export declare function detectGraphWriteCollapse(expected: number, 
+/**
+ * Relationships readable from the DB, or `undefined` when the count could
+ * not be READ at all (no connection, a query that threw).
+ *
+ * The distinction is load-bearing and was got wrong once: `getLbugStats`
+ * reports `edges: 0` for "no connection", "query threw" AND "empty table"
+ * alike, so passing it straight in made every run without a readable DB look
+ * like a total collapse. An unmeasurable count is not a measured zero —
+ * accepting `undefined` here is what keeps this check from committing the
+ * same confident-zero error it exists to catch.
+ */
+persisted: number | undefined): GraphWriteCollapseVerdict;
 /** Stable machine-readable reasons an index cannot be certified complete. */
-export declare function getIndexIncompleteReasons(meta: Pick<RepoMeta, 'incrementalInProgress' | 'embeddingCheckpoint'> | null | undefined): IndexIncompleteReason[];
+export declare function getIndexIncompleteReasons(meta: Pick<RepoMeta, 'incrementalInProgress' | 'embeddingCheckpoint' | 'graphWriteCollapsed'> | null | undefined): IndexIncompleteReason[];

package/dist/core/index-freshness.js

@@ -1,13 +1,120 @@
+import { checkpointKind } from './embedding-checkpoint.js';
 export const INDEX_INCOMPLETE_REASONS = [
     'incremental-in-progress',
     'embedding-checkpoint-pending',
+    'embedding-count-unverified',
+    'graph-write-collapsed',
 ];
+/**
+ * Fraction of the pipeline's relationship count that must survive into the DB
+ * before the write counts as collapsed. Deliberately generous: this detects
+ * "most of the graph did not persist" (the reported case lost ~91%), not a
+ * per-edge reconciliation.
+ */
+export const GRAPH_WRITE_COLLAPSE_RATIO = 0.5;
+/**
+ * Below this many relationships the ratio is meaningless — a handful of edges
+ * lost to legitimate filtering would trip it — so small repos are exempt.
+ */
+export const GRAPH_WRITE_COLLAPSE_MIN_EDGES = 100;
+/**
+ * Decide whether a finished write collapsed, comparing what the pipeline
+ * produced against what the DB hands back.
+ *
+ * A RATIO, not equality: some relationship types do not round-trip one-for-one
+ * and `--pdg` writes MORE rows into the same table, so demanding equality would
+ * fire on healthy runs. Only a collapse is a defect.
+ *
+ * FAIL-SAFE at `expected === 0`: an implementation that offloads relationships
+ * out of memory may not be able to report a total, and a false "your index is
+ * broken" is worse than a missed one. That case is `'unmeasurable'`, NOT
+ * `'healthy'` — nothing was compared, so nothing was cleared.
+ *
+ * Returns a THREE-WAY verdict rather than `{...} | undefined`. The absent value
+ * meant both "measured, fine" and "could not measure", and the caller — which
+ * decides whether to keep or erase the persisted `graph-write-collapsed` stamp —
+ * cannot tell those apart from a shared `undefined`. It guessed by write mode
+ * instead, so a full run whose structural count threw took the
+ * "no collapse ⇒ clear it" branch and deleted a stamp recording real loss.
+ */
+export function detectGraphWriteCollapse(expected, 
+/**
+ * Relationships readable from the DB, or `undefined` when the count could
+ * not be READ at all (no connection, a query that threw).
+ *
+ * The distinction is load-bearing and was got wrong once: `getLbugStats`
+ * reports `edges: 0` for "no connection", "query threw" AND "empty table"
+ * alike, so passing it straight in made every run without a readable DB look
+ * like a total collapse. An unmeasurable count is not a measured zero —
+ * accepting `undefined` here is what keeps this check from committing the
+ * same confident-zero error it exists to catch.
+ */
+persisted) {
+    // Both sides must be REAL NUMBERS before any comparison. A non-numeric
+    // `expected` (a graph implementation that reports no total, a lightweight
+    // pipeline result) does not merely skip the guards — it INVERTS them:
+    // `undefined < 100` is false, so the min-edges exemption never fires, and
+    // `0 >= undefined * 0.5` is `0 >= NaN`, also false, so the ratio check
+    // "passes" too and a healthy run is reported as a total collapse. Comparing
+    // against a non-number is the one way this check can manufacture the exact
+    // false certainty it was written to prevent.
+    if (!Number.isFinite(expected)) {
+        return { verdict: 'unmeasurable', reason: 'expected-unavailable' };
+    }
+    if (typeof persisted !== 'number' || !Number.isFinite(persisted)) {
+        return { verdict: 'unmeasurable', reason: 'persisted-unreadable' };
+    }
+    const expectedCount = expected;
+    const persistedCount = persisted;
+    // FAIL-SAFE, and `'unmeasurable'` rather than `'healthy'`: a zero expectation
+    // is the documented "could not report a total" case, not evidence the write
+    // went well. Reporting it as an all-clear would let a run that measured
+    // nothing erase a stamp recording a previous run's real loss.
+    if (expectedCount === 0) {
+        return { verdict: 'unmeasurable', reason: 'expected-unavailable' };
+    }
+    // A TOTAL loss is never small enough to excuse. The min-edges exemption
+    // exists for "a handful of edges lost to legitimate filtering", which its own
+    // docstring says — it does not describe a persisted count of zero. Evaluated
+    // before the exemption because the exemption looked only at `expected`:
+    // `expected = 99, persisted = 0` lost every single edge and still returned
+    // no verdict, leaving the metadata fresh and the CLI reporting success.
+    if (expectedCount > 0 && persistedCount === 0) {
+        return { verdict: 'collapsed', expected: expectedCount, persisted: persistedCount };
+    }
+    // The small-repo exemption and the cleared ratio are both `'healthy'`, not
+    // `'unmeasurable'`: both counts WERE taken, and the comparison ran. Calling
+    // the exemption a non-verdict would make a stamp unclearable on any repo that
+    // shrank below the threshold — a permanent forced-rebuild wedge, which is the
+    // failure this taxonomy exists to avoid rather than to relocate.
+    if (expectedCount < GRAPH_WRITE_COLLAPSE_MIN_EDGES)
+        return { verdict: 'healthy' };
+    if (persistedCount >= expectedCount * GRAPH_WRITE_COLLAPSE_RATIO)
+        return { verdict: 'healthy' };
+    return { verdict: 'collapsed', expected: expectedCount, persisted: persistedCount };
+}
 /** Stable machine-readable reasons an index cannot be certified complete. */
 export function getIndexIncompleteReasons(meta) {
     const reasons = [];
     if (meta?.incrementalInProgress)
         reasons.push('incremental-in-progress');
-    if (meta?.embeddingCheckpoint)
-        reasons.push('embedding-checkpoint-pending');
+    // The run finished and wrote metadata, but far fewer edges reached the DB
+    // than the pipeline produced — the "refresh reported success, the index is
+    // unusable" failure. Without this the index reads as fresh and every tool
+    // answers from a graph missing most of its edges, which is indistinguishable
+    // from a codebase that genuinely has no such relationships.
+    if (meta?.graphWriteCollapsed)
+        reasons.push('graph-write-collapsed');
+    if (meta?.embeddingCheckpoint) {
+        // The three checkpoint kinds are not one operator-facing state. GUARDRAILS
+        // and the runbook document `embedding-checkpoint-pending` as "N node(s)
+        // lost their embeddings to endpoint failures" — true for 'interrupted' and
+        // 'partial', a lie for 'unverified-count', whose pending set is empty and
+        // whose only defect is a count nobody could measure (see the `kind` doc in
+        // repo-manager.ts).
+        reasons.push(checkpointKind(meta.embeddingCheckpoint) === 'unverified-count'
+            ? 'embedding-count-unverified'
+            : 'embedding-checkpoint-pending');
+    }
     return reasons;
 }

package/dist/core/ingestion/call-processor.d.ts

@@ -16,11 +16,22 @@
  */
 import { KnowledgeGraph } from '../graph/types.js';
 import type { SemanticModel, SymbolTableReader } from './model/index.js';
+import type { ParsedImport, SymbolDefinition } from '../../_shared/index.js';
 import type { ExtractedRoute, ExtractedFetchCall } from './workers/parse-worker.js';
 import type { ExtractedDecoratorRoute } from './workers/parse-worker.js';
 /** Per-file resolved type bindings for exported symbols.
  *  Consumed by the cross-file re-resolution / enrichment pass. */
 export type ExportedTypeMap = Map<string, Map<string, string>>;
+interface RouteResolutionFile {
+    readonly filePath: string;
+    readonly parsedImports: readonly ParsedImport[];
+    readonly localDefs: readonly SymbolDefinition[];
+}
+interface RouteHandlerResolutionContext {
+    readonly files: readonly RouteResolutionFile[];
+    readonly resolveImportTarget: (parsedImport: ParsedImport, fromFile: string) => string | null;
+    readonly isExportedSymbol: (nodeId: string) => boolean;
+}
 /** Record one exported graph node into the incremental ExportedTypeMap. */
 export declare const accumulateExportedTypesFromParsedNode: (result: ExportedTypeMap, node: {
     id: string;
@@ -86,7 +97,7 @@ export declare const processRoutesFromExtracted: (graph: KnowledgeGraph, extract
  * `handlerSymbolId`; the extractor then falls back to source scan for that route
  * (fail-open, no regression, never a wrong handler).
  */
-export declare function resolveRouteHandlerSymbols(model: SemanticModel, extractedRoutes: readonly ExtractedRoute[], decoratorRoutes: readonly ExtractedDecoratorRoute[]): Map<string, string>;
+export declare function resolveRouteHandlerSymbols(model: SemanticModel, extractedRoutes: readonly ExtractedRoute[], decoratorRoutes: readonly ExtractedDecoratorRoute[], routeContext?: RouteHandlerResolutionContext): Map<string, string>;
 /**
  * Extract property access keys from a consumer file's source code near fetch calls.
  *
@@ -112,3 +123,4 @@ export declare const extractConsumerAccessedKeys: (content: string) => string[];
  */
 export declare const processNextjsFetchRoutes: (graph: KnowledgeGraph, fetchCalls: ExtractedFetchCall[], routeUrlToKeys: Map<string, string[]>, // routeURL → route node keys at that URL
 consumerContents?: Map<string, string>) => void;
+export {};