sdl-mcp 0.11.12 → 0.11.13

package/dist/indexer/indexer.js

@@ -11,7 +11,7 @@ import { finalizeDerivedState } from "./finalize-derived-state.js";
 import { watchRepositoryWithIndexer } from "./watcher.js";
 import { IndexingConfigSchema, } from "../config/types.js";
 import { loadConfig } from "../config/loadConfig.js";
-import { buildDeferredIndexes, closeLadybugDb, flushStaleFinalizers, getLadybugConn, getLadybugDbPath, initLadybugDb, preIndexCheckpoint, withWriteConn, } from "../db/ladybug.js";
+import { buildDeferredIndexes, closeLadybugDb, ensureCriticalSymbolFtsIndex, flushStaleFinalizers, getLadybugConn, getLadybugDbPath, initLadybugDb, preIndexCheckpoint, withWriteConn, } from "../db/ladybug.js";
 import { withPostIndexWriteSession } from "../db/write-session.js";
 import * as ladybugDb from "../db/ladybug-queries.js";
 import { derivedStateIsStale, getDerivedState, markDerivedStateDirty, recordDerivedStateError, } from "../db/ladybug-derived-state.js";
@@ -1461,6 +1461,11 @@ async function indexRepoImpl(repoId, mode, onProgress, signal, options, scipPreR
             onProgress,
         }));
         recordFinalizeIndexingSubphaseTimings(finalizeResult.timings);
+        await measurePhase("ensureCriticalSymbolFts", async () => {
+            await ensureCriticalSymbolFtsIndex({
+                recordTiming: recordIndexSubphaseTiming,
+            });
+        });
         const freshConn = await getLadybugConn();
         const derivedResult = params.skipDerivedStateReason
             ? await measurePhase("skipDerivedState", async () => {
@@ -1655,673 +1660,691 @@ async function indexRepoImpl(repoId, mode, onProgress, signal, options, scipPreR
         providerFirstExecutor &&
         providerFirstIncrementalBootstrapped) {
         providerFirstTimingStartedAt = Date.now();
-        emitProviderFirstProgress(onProgress, "coverageScan", {
-            message: "scanning repository for provider-first coverage",
-        });
-        const providerCoverageScan = await measureProviderFirstPhase("coverageScan", "providerFirstCoverageScan", () => scanRepoForIndex({
-            repoId,
-            repoRoot: repoRow.rootPath,
-            config,
-            onProgress,
-            deleteRemovedFiles: false,
-        }));
-        emitProviderFirstProgress(onProgress, "coverageScan", {
-            stageCurrent: providerCoverageScan.files.length,
-            stageTotal: providerCoverageScan.files.length,
-            message: `scanned ${providerCoverageScan.files.length} file(s) for provider-first coverage`,
-        });
-        let providerFirstRemovedFilesDeleted = false;
-        if (providerFirstIncrementalActive &&
-            providerCoverageScan.removedFileIds.length > 0) {
-            await measureProviderFirstPhase("deleteRemovedFiles", "providerFirstIncrementalDeleteRemovedFiles", () => withWriteConn(async (conn) => {
-                await ladybugDb.withTransaction(conn, async (txConn) => {
-                    await ladybugDb.deleteFilesByIds(txConn, providerCoverageScan.removedFileIds);
-                });
-            }, postIndexSessionTimeoutMs));
-            providerFirstRemovedFilesDeleted = true;
-        }
-        const providerChangedFiles = providerFirstIncrementalActive
-            ? providerFirstIncrementalChangedFiles(providerCoverageScan)
-            : providerCoverageScan.files;
-        const providerExecutionScan = providerFirstIncrementalActive
-            ? filterProviderFirstIncrementalScan(providerCoverageScan, providerChangedFiles)
-            : providerCoverageScan;
-        if (providerFirstIncrementalActive && providerChangedFiles.length === 0) {
-            providerFirstScan = providerCoverageScan;
+        try {
             emitProviderFirstProgress(onProgress, "coverageScan", {
-                stageCurrent: 0,
-                stageTotal: 0,
-                message: "no changed files for provider-first incremental execution",
+                message: "scanning repository for provider-first coverage",
             });
-        }
-        let providerResult;
-        if (!providerFirstIncrementalActive || providerChangedFiles.length > 0) {
-            try {
-                let providerScipPreRefresh = activeScipPreRefresh;
-                let providerIncrementalTempPaths = [];
+            const providerCoverageScan = await measureProviderFirstPhase("coverageScan", "providerFirstCoverageScan", () => scanRepoForIndex({
+                repoId,
+                repoRoot: repoRow.rootPath,
+                config,
+                onProgress,
+                deleteRemovedFiles: false,
+            }));
+            emitProviderFirstProgress(onProgress, "coverageScan", {
+                stageCurrent: providerCoverageScan.files.length,
+                stageTotal: providerCoverageScan.files.length,
+                message: `scanned ${providerCoverageScan.files.length} file(s) for provider-first coverage`,
+            });
+            let providerFirstRemovedFilesDeleted = false;
+            if (providerFirstIncrementalActive &&
+                providerCoverageScan.removedFileIds.length > 0) {
+                await measureProviderFirstPhase("deleteRemovedFiles", "providerFirstIncrementalDeleteRemovedFiles", () => withWriteConn(async (conn) => {
+                    await ladybugDb.withTransaction(conn, async (txConn) => {
+                        await ladybugDb.deleteFilesByIds(txConn, providerCoverageScan.removedFileIds);
+                    });
+                }, postIndexSessionTimeoutMs));
+                providerFirstRemovedFilesDeleted = true;
+            }
+            const providerChangedFiles = providerFirstIncrementalActive
+                ? providerFirstIncrementalChangedFiles(providerCoverageScan)
+                : providerCoverageScan.files;
+            const providerExecutionScan = providerFirstIncrementalActive
+                ? filterProviderFirstIncrementalScan(providerCoverageScan, providerChangedFiles)
+                : providerCoverageScan;
+            if (providerFirstIncrementalActive && providerChangedFiles.length === 0) {
+                providerFirstScan = providerCoverageScan;
+                emitProviderFirstProgress(onProgress, "coverageScan", {
+                    stageCurrent: 0,
+                    stageTotal: 0,
+                    message: "no changed files for provider-first incremental execution",
+                });
+            }
+            let providerResult;
+            if (!providerFirstIncrementalActive || providerChangedFiles.length > 0) {
                 try {
-                    if (providerFirstExecutor === "scipIncremental") {
-                        const scopedScip = await measureProviderFirstPhase("scipIncrementalGenerate", "providerFirstScipIncrementalGenerate", () => runProviderFirstIncrementalScipIo({
-                            repoId,
-                            repoRoot: repoRow.rootPath,
-                            repoConfig: config,
-                            appConfig,
-                            changedFiles: providerChangedFiles,
-                            signal,
-                        }));
-                        providerScipPreRefresh = scopedScip.diagnostics;
-                        activeScipPreRefresh = scopedScip.diagnostics;
-                        providerIncrementalTempPaths = scopedScip.tempPaths;
-                    }
-                    providerResult = await measureProviderFirstPhase("providerCollection", providerFirstLspExecutor(providerFirstExecutor)
-                        ? providerFirstIncrementalActive
-                            ? "providerFirstLspIncremental"
-                            : "providerFirstLspFull"
-                        : providerFirstIncrementalActive
-                            ? "providerFirstScipIncremental"
-                            : "providerFirstScipFull", () => {
-                        if (providerFirstExecutor === "lspFull") {
-                            return executeProviderFirstLspFull({
+                    let providerScipPreRefresh = activeScipPreRefresh;
+                    let providerIncrementalTempPaths = [];
+                    try {
+                        if (providerFirstExecutor === "scipIncremental") {
+                            const scopedScip = await measureProviderFirstPhase("scipIncrementalGenerate", "providerFirstScipIncrementalGenerate", () => runProviderFirstIncrementalScipIo({
                                 repoId,
                                 repoRoot: repoRow.rootPath,
-                                config: appConfig,
-                                scannedFiles: providerExecutionScan.files,
-                                recordPhaseTiming: recordProviderFirstPhaseTiming,
+                                repoConfig: config,
+                                appConfig,
+                                changedFiles: providerChangedFiles,
                                 signal,
-                            });
+                            }));
+                            providerScipPreRefresh = scopedScip.diagnostics;
+                            activeScipPreRefresh = scopedScip.diagnostics;
+                            providerIncrementalTempPaths = scopedScip.tempPaths;
                         }
-                        if (providerFirstExecutor === "lspIncremental") {
-                            return executeProviderFirstLspIncremental({
+                        providerResult = await measureProviderFirstPhase("providerCollection", providerFirstLspExecutor(providerFirstExecutor)
+                            ? providerFirstIncrementalActive
+                                ? "providerFirstLspIncremental"
+                                : "providerFirstLspFull"
+                            : providerFirstIncrementalActive
+                                ? "providerFirstScipIncremental"
+                                : "providerFirstScipFull", () => {
+                            if (providerFirstExecutor === "lspFull") {
+                                return executeProviderFirstLspFull({
+                                    repoId,
+                                    repoRoot: repoRow.rootPath,
+                                    config: appConfig,
+                                    scannedFiles: providerExecutionScan.files,
+                                    recordPhaseTiming: recordProviderFirstPhaseTiming,
+                                    signal,
+                                });
+                            }
+                            if (providerFirstExecutor === "lspIncremental") {
+                                return executeProviderFirstLspIncremental({
+                                    repoId,
+                                    repoRoot: repoRow.rootPath,
+                                    config: appConfig,
+                                    scannedFiles: providerExecutionScan.files,
+                                    recordPhaseTiming: recordProviderFirstPhaseTiming,
+                                    signal,
+                                });
+                            }
+                            const scipParams = {
                                 repoId,
                                 repoRoot: repoRow.rootPath,
                                 config: appConfig,
+                                generatedIndexes: providerScipPreRefresh?.generatedIndexes,
+                                generatorFailures: providerScipPreRefresh?.failures,
+                                generatorCacheKey: providerScipPreRefresh?.cache?.key,
+                                scannedPaths: providerExecutionScan.files.map((file) => file.path),
                                 scannedFiles: providerExecutionScan.files,
                                 recordPhaseTiming: recordProviderFirstPhaseTiming,
+                                onProgress,
                                 signal,
-                            });
-                        }
-                        const scipParams = {
-                            repoId,
-                            repoRoot: repoRow.rootPath,
-                            config: appConfig,
-                            generatedIndexes: providerScipPreRefresh?.generatedIndexes,
-                            generatorFailures: providerScipPreRefresh?.failures,
-                            generatorCacheKey: providerScipPreRefresh?.cache?.key,
-                            scannedPaths: providerExecutionScan.files.map((file) => file.path),
-                            scannedFiles: providerExecutionScan.files,
-                            recordPhaseTiming: recordProviderFirstPhaseTiming,
-                            onProgress,
-                            signal,
-                        };
-                        return providerFirstExecutor === "scipIncremental"
-                            ? executeProviderFirstScipIncremental(scipParams)
-                            : executeProviderFirstScipFull(scipParams);
-                    });
-                }
-                finally {
-                    await cleanupProviderFirstIncrementalTempPaths(providerIncrementalTempPaths);
-                }
-            }
-            catch (err) {
-                if (err instanceof ProviderFirstGraphValidationError) {
-                    throw err;
+                            };
+                            return providerFirstExecutor === "scipIncremental"
+                                ? executeProviderFirstScipIncremental(scipParams)
+                                : executeProviderFirstScipFull(scipParams);
+                        });
+                    }
+                    finally {
+                        await cleanupProviderFirstIncrementalTempPaths(providerIncrementalTempPaths);
+                    }
                 }
-                const reason = err instanceof Error
-                    ? err.message
-                    : `provider-first SCIP execution failed: ${String(err)}`;
-                if (providerFirst.requestedMode === "auto") {
-                    const fallbackReason = formatProviderFirstAutoFallbackReason({
-                        reason,
-                        providerFirstIncrementalActive,
-                    });
-                    logger.warn("indexRepo: provider-first execution failed, using legacy fallback", {
-                        repoId,
-                        reason: fallbackReason,
-                    });
-                    providerFirstExecutionFallback = providerFirstFallbackSummary([
-                        fallbackReason,
-                    ]);
-                    if (providerFirstIncrementalActive) {
-                        // Keep provider-first incremental failures scoped; otherwise the
-                        // legacy safety fallback degenerates into a full repo pass.
-                        providerFirstScan = providerExecutionScan;
-                        for (const file of providerExecutionScan.files) {
-                            providerFirstFallbackPaths.add(file.path);
+                catch (err) {
+                    if (err instanceof ProviderFirstGraphValidationError) {
+                        throw err;
+                    }
+                    const reason = err instanceof Error
+                        ? err.message
+                        : `provider-first SCIP execution failed: ${String(err)}`;
+                    if (providerFirst.requestedMode === "auto") {
+                        const fallbackReason = formatProviderFirstAutoFallbackReason({
+                            reason,
+                            providerFirstIncrementalActive,
+                        });
+                        logger.warn("indexRepo: provider-first execution failed, using legacy fallback", {
+                            repoId,
+                            reason: fallbackReason,
+                        });
+                        providerFirstExecutionFallback = providerFirstFallbackSummary([
+                            fallbackReason,
+                        ]);
+                        if (providerFirstIncrementalActive) {
+                            // Keep provider-first incremental failures scoped; otherwise the
+                            // legacy safety fallback degenerates into a full repo pass.
+                            providerFirstScan = providerExecutionScan;
+                            for (const file of providerExecutionScan.files) {
+                                providerFirstFallbackPaths.add(file.path);
+                            }
+                            providerFirstLegacyFallbackComplete = true;
+                            providerFirstLegacyFallbackFileCount = providerExecutionScan.files.length;
+                            providerFirstLegacyFallbackSamplePaths = providerExecutionScan.files
+                                .map((file) => file.path)
+                                .slice(0, 10);
+                            providerFirstLegacyFallbackStartedAt = Date.now();
                         }
-                        providerFirstLegacyFallbackComplete = true;
-                        providerFirstLegacyFallbackFileCount = providerExecutionScan.files.length;
-                        providerFirstLegacyFallbackSamplePaths = providerExecutionScan.files
-                            .map((file) => file.path)
-                            .slice(0, 10);
-                        providerFirstLegacyFallbackStartedAt = Date.now();
                     }
-                }
-                else {
-                    throw err;
+                    else {
+                        throw err;
+                    }
                 }
             }
-        }
-        if (providerResult) {
-            const executionFailureReasons = providerFirstFatalFailureReasons({
-                failures: "failures" in providerResult ? providerResult.failures : [],
-                providerRowsAvailable: providerResult.rows.files.length > 0,
-            });
-            if (executionFailureReasons.length > 0) {
-                if (providerFirst.requestedMode === "auto") {
-                    logger.warn("indexRepo: provider-first execution had failures, using legacy fallback", {
-                        repoId,
-                        reasons: executionFailureReasons,
-                    });
-                    providerFirstExecutionFallback = providerFirstFallbackSummary(executionFailureReasons);
+            if (providerResult) {
+                const executionFailureReasons = providerFirstFatalFailureReasons({
+                    failures: "failures" in providerResult ? providerResult.failures : [],
+                    providerRowsAvailable: providerResult.rows.files.length > 0,
+                });
+                if (executionFailureReasons.length > 0) {
+                    if (providerFirst.requestedMode === "auto") {
+                        logger.warn("indexRepo: provider-first execution had failures, using legacy fallback", {
+                            repoId,
+                            reasons: executionFailureReasons,
+                        });
+                        providerFirstExecutionFallback = providerFirstFallbackSummary(executionFailureReasons);
+                    }
+                    else {
+                        throw new Error(`Provider-first indexing cannot execute for ${repoId}: ${executionFailureReasons.join("; ")}`);
+                    }
                 }
                 else {
-                    throw new Error(`Provider-first indexing cannot execute for ${repoId}: ${executionFailureReasons.join("; ")}`);
-                }
-            }
-            else {
-                const providerScan = providerExecutionScan;
-                providerFirstScan = providerScan;
-                if (providerFactsShouldDropCoveragePayloads(providerResult.facts)) {
-                    clearProviderFactPayloadsForCoverageAnalysis(providerResult.facts);
+                    const providerScan = providerExecutionScan;
+                    providerFirstScan = providerScan;
+                    if (providerFactsShouldDropCoveragePayloads(providerResult.facts)) {
+                        clearProviderFactPayloadsForCoverageAnalysis(providerResult.facts);
+                        emitProviderFirstProgress(onProgress, "coverageAnalyze", {
+                            message: "large provider occurrence payloads released",
+                        });
+                    }
+                    const scanScopedProvider = filterProviderFirstDataToScannedScope({
+                        rows: providerResult.rows,
+                        facts: providerResult.facts,
+                        scannedPaths: providerScan.files.map((file) => file.path),
+                    });
                     emitProviderFirstProgress(onProgress, "coverageAnalyze", {
-                        message: "large provider occurrence payloads released",
+                        message: "provider rows filtered to scan scope",
                     });
-                }
-                const scanScopedProvider = filterProviderFirstDataToScannedScope({
-                    rows: providerResult.rows,
-                    facts: providerResult.facts,
-                    scannedPaths: providerScan.files.map((file) => file.path),
-                });
-                emitProviderFirstProgress(onProgress, "coverageAnalyze", {
-                    message: "provider rows filtered to scan scope",
-                });
-                const scanScopedProviderPaths = scanScopedProvider.rows.files.map((file) => file.relPath);
-                const scanHasCppSemanticPaths = providerScan.files.some((file) => isCppSemanticScanPath(file.path));
-                const semanticEligiblePaths = scanHasCppSemanticPaths
-                    ? await resolveProviderFirstSemanticEligiblePaths({
-                        repoRoot: repoRow.rootPath,
+                    const scanScopedProviderPaths = scanScopedProvider.rows.files.map((file) => file.relPath);
+                    const scanHasCppSemanticPaths = providerScan.files.some((file) => isCppSemanticScanPath(file.path));
+                    const semanticEligiblePaths = scanHasCppSemanticPaths
+                        ? await resolveProviderFirstSemanticEligiblePaths({
+                            repoRoot: repoRow.rootPath,
+                            scannedPaths: providerScan.files.map((file) => file.path),
+                            providerPaths: scanScopedProviderPaths,
+                        })
+                        : undefined;
+                    const coverageReport = analyzeProviderFirstCoverage({
                         scannedPaths: providerScan.files.map((file) => file.path),
+                        semanticEligiblePaths: semanticEligiblePaths && semanticEligiblePaths.size > 0
+                            ? semanticEligiblePaths
+                            : undefined,
                         providerPaths: scanScopedProviderPaths,
-                    })
-                    : undefined;
-                const coverageReport = analyzeProviderFirstCoverage({
-                    scannedPaths: providerScan.files.map((file) => file.path),
-                    semanticEligiblePaths: semanticEligiblePaths && semanticEligiblePaths.size > 0
-                        ? semanticEligiblePaths
-                        : undefined,
-                    providerPaths: scanScopedProviderPaths,
-                    coverage: scanScopedProvider.facts.coverage,
-                    symbols: scanScopedProvider.facts.symbols,
-                    occurrences: scanScopedProvider.facts.occurrences,
-                    sourceLinesByPath: scanScopedProvider.facts.sourceLinesByPath,
-                });
-                emitProviderFirstProgress(onProgress, "coverageAnalyze", {
-                    message: "provider coverage analyzed",
-                });
-                if (coverageReport.fatalReasons.length > 0) {
-                    throw new Error(`Provider-first indexing cannot execute for ${repoId}: ${coverageReport.fatalReasons.join("; ")}`);
-                }
-                else {
-                    const legacyFallbackPlan = resolveProviderFirstLegacyFallbackPlan({
-                        fallbackFileCount: coverageReport.fallbackPaths.size,
-                        semanticEligibleFallbackFileCount: coverageReport.summary.semanticEligibilityGap?.totalFiles,
-                        maxLegacyFallbackFiles: providerFirstConfig.maxLegacyFallbackFiles,
-                        maxSemanticEligibleFallbackFiles: providerFirstConfig.maxSemanticEligibleFallbackFiles,
+                        coverage: scanScopedProvider.facts.coverage,
+                        symbols: scanScopedProvider.facts.symbols,
+                        occurrences: scanScopedProvider.facts.occurrences,
+                        sourceLinesByPath: scanScopedProvider.facts.sourceLinesByPath,
                     });
-                    const skippedLegacyFallbackReason = skippedProviderFirstLegacyFallbackReason(legacyFallbackPlan);
-                    const readinessGates = resolveProviderFirstReadinessGates({
-                        callProofSkipReason: callProofSkipDerivedStateReason(coverageReport.callProofIncompletePaths),
-                        skippedLegacyFallbackReason,
+                    emitProviderFirstProgress(onProgress, "coverageAnalyze", {
+                        message: "provider coverage analyzed",
                     });
-                    providerFirstSkipDerivedStateReason =
-                        readinessGates.skipDerivedStateReason;
-                    providerFirstShadowStagingSkipReason =
-                        readinessGates.shadowStagingSkipReason;
-                    if (scopedSourceFileListActive) {
-                        providerFirstShadowStagingSkipReason =
-                            providerFirstShadowStagingSkipReason
-                                ? `${providerFirstShadowStagingSkipReason}; ${scopedSourceFileListReason}`
-                                : scopedSourceFileListReason;
-                    }
-                    if (providerFirstShadowRepoScopeSkipReason) {
-                        // ponytail: revisit multi-repo shadow DBs when shadow builds can copy
-                        // a complete DB, including non-target repos, before activation.
-                        providerFirstShadowStagingSkipReason =
-                            providerFirstShadowStagingSkipReason
-                                ? `${providerFirstShadowStagingSkipReason}; ${providerFirstShadowRepoScopeSkipReason}`
-                                : providerFirstShadowRepoScopeSkipReason;
+                    if (coverageReport.fatalReasons.length > 0) {
+                        throw new Error(`Provider-first indexing cannot execute for ${repoId}: ${coverageReport.fatalReasons.join("; ")}`);
                     }
-                    if (providerFirstIncrementalActive) {
-                        const incrementalShadowSkipReason = "shadow staging skipped because provider-first incremental materializes only changed files";
+                    else {
+                        const legacyFallbackPlan = resolveProviderFirstLegacyFallbackPlan({
+                            fallbackFileCount: coverageReport.fallbackPaths.size,
+                            semanticEligibleFallbackFileCount: coverageReport.summary.semanticEligibilityGap?.totalFiles,
+                            maxLegacyFallbackFiles: providerFirstConfig.maxLegacyFallbackFiles,
+                            maxSemanticEligibleFallbackFiles: providerFirstConfig.maxSemanticEligibleFallbackFiles,
+                        });
+                        const skippedLegacyFallbackReason = skippedProviderFirstLegacyFallbackReason(legacyFallbackPlan);
+                        const readinessGates = resolveProviderFirstReadinessGates({
+                            callProofSkipReason: callProofSkipDerivedStateReason(coverageReport.callProofIncompletePaths),
+                            skippedLegacyFallbackReason,
+                        });
+                        providerFirstSkipDerivedStateReason =
+                            readinessGates.skipDerivedStateReason;
                         providerFirstShadowStagingSkipReason =
-                            providerFirstShadowStagingSkipReason
-                                ? `${providerFirstShadowStagingSkipReason}; ${incrementalShadowSkipReason}`
-                                : incrementalShadowSkipReason;
-                    }
-                    const legacyFallbackPaths = selectProviderFirstLegacyFallbackPaths({
-                        fallbackPaths: coverageReport.fallbackPaths,
-                        semanticEligiblePaths,
-                        parsedFiles: legacyFallbackPlan.parsedFiles,
-                    });
-                    const providerRowsExcludedByLegacyFallback = legacyFallbackPlan.runLegacyFallback
-                        ? selectProviderRowsExcludedByLegacyFallback({
-                            fallbackPaths: legacyFallbackPaths,
-                            coverage: scanScopedProvider.facts.coverage,
-                        })
-                        : new Set();
-                    const materializedRows = filterProviderRowsForFallback(scanScopedProvider.rows, providerRowsExcludedByLegacyFallback);
-                    await measureProviderFirstPhase("persistProvenance", "providerFirstPersistProvenance", () => withWriteConn((conn) => persistProviderFirstProvenance(conn, scanScopedProvider.facts)));
-                    // The provider fact set can include every SCIP occurrence and source
-                    // line. Drop it before legacy fallback and versioning so large repos
-                    // do not carry decoded provider payloads into post-index finalization.
-                    clearProviderFactPayloadsForGc(providerResult.facts);
-                    if (scanScopedProvider.facts !== providerResult.facts) {
-                        clearProviderFactPayloadsForGc(scanScopedProvider.facts);
-                    }
-                    if (providerResult.rows !== materializedRows) {
-                        clearProviderGraphRowsForGc(providerResult.rows);
-                    }
-                    if (scanScopedProvider.rows !== materializedRows &&
-                        scanScopedProvider.rows !== providerResult.rows) {
-                        clearProviderGraphRowsForGc(scanScopedProvider.rows);
-                    }
-                    await measureProviderFirstPhase("postProviderGc", "providerFirstPostProviderGc", () => flushProviderFirstPayloadFinalizers());
-                    emitProviderFirstProgress(onProgress, "coverageAnalyze", {
-                        message: "provider payload finalizers flushed",
-                    });
-                    providerFirstProviderRows = materializedRows;
-                    providerFirstGenerationId = providerResult.generationId;
-                    applyScannedFileMetadataToProviderRows({
-                        rows: materializedRows,
-                        scannedFiles: providerScan.files,
-                    });
-                    let shadowBuild;
-                    if (!legacyFallbackPlan.runLegacyFallback) {
-                        if (providerFirstShadowStagingSkipReason) {
-                            const shadowStageTotal = providerFirstGraphRowTotal(materializedRows);
-                            emitProviderFirstProgress(onProgress, "shadowStage", {
-                                stageCurrent: 0,
-                                stageTotal: shadowStageTotal,
-                                message: `shadow staging skipped: ${providerFirstShadowStagingSkipReason}`,
-                            });
-                            shadowBuild = skippedProviderFirstShadowBuild({
-                                generationId: providerResult.generationId,
-                                activation: providerFirstConfig.activation,
-                                requestedFormat: providerFirstConfig.stagingFormat,
-                                rows: materializedRows,
-                                reason: providerFirstShadowStagingSkipReason,
-                            });
+                            readinessGates.shadowStagingSkipReason;
+                        if (scopedSourceFileListActive) {
+                            providerFirstShadowStagingSkipReason =
+                                providerFirstShadowStagingSkipReason
+                                    ? `${providerFirstShadowStagingSkipReason}; ${scopedSourceFileListReason}`
+                                    : scopedSourceFileListReason;
                         }
-                        else {
-                            const shadowStageTotal = providerFirstGraphRowTotal(materializedRows);
-                            emitProviderFirstProgress(onProgress, "shadowStage", {
-                                stageCurrent: 0,
-                                stageTotal: shadowStageTotal,
-                                message: "staging provider rows for shadow bulk load",
-                            });
-                            shadowBuild = await measureProviderFirstPhase("shadowStage", "providerFirstShadowStage", () => stageProviderFirstShadowBuild({
-                                repoId,
-                                generationId: providerResult.generationId,
-                                activation: providerFirstConfig.activation,
-                                requestedFormat: providerFirstConfig.stagingFormat,
-                                activeDbPath: getLadybugDbPath(),
-                                repoRoot: repoRow.rootPath,
-                                repoConfigJson: repoRow.configJson,
-                                rows: materializedRows,
-                            }));
-                            shadowBuild.activationResult =
-                                summarizeProviderFirstShadowActivationReadiness({
-                                    shadowBuild,
-                                    fallbackFiles: 0,
-                                    graphDerivedStateReady: providerFirstSkipDerivedStateReason === undefined,
-                                    shadowContainsFinalizedGraph: false,
-                                    finalizedGraphReasons: providerFirstSkipDerivedStateReason
-                                        ? [providerFirstSkipDerivedStateReason]
-                                        : undefined,
+                        if (providerFirstShadowRepoScopeSkipReason) {
+                            // ponytail: revisit multi-repo shadow DBs when shadow builds can copy
+                            // a complete DB, including non-target repos, before activation.
+                            providerFirstShadowStagingSkipReason =
+                                providerFirstShadowStagingSkipReason
+                                    ? `${providerFirstShadowStagingSkipReason}; ${providerFirstShadowRepoScopeSkipReason}`
+                                    : providerFirstShadowRepoScopeSkipReason;
+                        }
+                        if (providerFirstIncrementalActive) {
+                            const incrementalShadowSkipReason = "shadow staging skipped because provider-first incremental materializes only changed files";
+                            providerFirstShadowStagingSkipReason =
+                                providerFirstShadowStagingSkipReason
+                                    ? `${providerFirstShadowStagingSkipReason}; ${incrementalShadowSkipReason}`
+                                    : incrementalShadowSkipReason;
+                        }
+                        const legacyFallbackPaths = selectProviderFirstLegacyFallbackPaths({
+                            fallbackPaths: coverageReport.fallbackPaths,
+                            semanticEligiblePaths,
+                            parsedFiles: legacyFallbackPlan.parsedFiles,
+                        });
+                        const providerRowsExcludedByLegacyFallback = legacyFallbackPlan.runLegacyFallback
+                            ? selectProviderRowsExcludedByLegacyFallback({
+                                fallbackPaths: legacyFallbackPaths,
+                                coverage: scanScopedProvider.facts.coverage,
+                            })
+                            : new Set();
+                        const materializedRows = filterProviderRowsForFallback(scanScopedProvider.rows, providerRowsExcludedByLegacyFallback);
+                        await measureProviderFirstPhase("persistProvenance", "providerFirstPersistProvenance", () => withWriteConn((conn) => persistProviderFirstProvenance(conn, scanScopedProvider.facts)));
+                        // The provider fact set can include every SCIP occurrence and source
+                        // line. Drop it before legacy fallback and versioning so large repos
+                        // do not carry decoded provider payloads into post-index finalization.
+                        clearProviderFactPayloadsForGc(providerResult.facts);
+                        if (scanScopedProvider.facts !== providerResult.facts) {
+                            clearProviderFactPayloadsForGc(scanScopedProvider.facts);
+                        }
+                        if (providerResult.rows !== materializedRows) {
+                            clearProviderGraphRowsForGc(providerResult.rows);
+                        }
+                        if (scanScopedProvider.rows !== materializedRows &&
+                            scanScopedProvider.rows !== providerResult.rows) {
+                            clearProviderGraphRowsForGc(scanScopedProvider.rows);
+                        }
+                        await measureProviderFirstPhase("postProviderGc", "providerFirstPostProviderGc", () => flushProviderFirstPayloadFinalizers());
+                        emitProviderFirstProgress(onProgress, "coverageAnalyze", {
+                            message: "provider payload finalizers flushed",
+                        });
+                        providerFirstProviderRows = materializedRows;
+                        providerFirstGenerationId = providerResult.generationId;
+                        applyScannedFileMetadataToProviderRows({
+                            rows: materializedRows,
+                            scannedFiles: providerScan.files,
+                        });
+                        let shadowBuild;
+                        if (!legacyFallbackPlan.runLegacyFallback) {
+                            if (providerFirstShadowStagingSkipReason) {
+                                const shadowStageTotal = providerFirstGraphRowTotal(materializedRows);
+                                emitProviderFirstProgress(onProgress, "shadowStage", {
+                                    stageCurrent: 0,
+                                    stageTotal: shadowStageTotal,
+                                    message: `shadow staging skipped: ${providerFirstShadowStagingSkipReason}`,
                                 });
-                            if (shadowBuild.status === "staged") {
-                                const stagedTotal = providerFirstShadowStageTotal(shadowBuild.counts);
+                                shadowBuild = skippedProviderFirstShadowBuild({
+                                    generationId: providerResult.generationId,
+                                    activation: providerFirstConfig.activation,
+                                    requestedFormat: providerFirstConfig.stagingFormat,
+                                    rows: materializedRows,
+                                    reason: providerFirstShadowStagingSkipReason,
+                                });
+                            }
+                            else {
+                                const shadowStageTotal = providerFirstGraphRowTotal(materializedRows);
                                 emitProviderFirstProgress(onProgress, "shadowStage", {
-                                    stageCurrent: stagedTotal,
-                                    stageTotal: stagedTotal,
-                                    message: "provider rows staged for shadow bulk load",
+                                    stageCurrent: 0,
+                                    stageTotal: shadowStageTotal,
+                                    message: "staging provider rows for shadow bulk load",
                                 });
+                                shadowBuild = await measureProviderFirstPhase("shadowStage", "providerFirstShadowStage", () => stageProviderFirstShadowBuild({
+                                    repoId,
+                                    generationId: providerResult.generationId,
+                                    activation: providerFirstConfig.activation,
+                                    requestedFormat: providerFirstConfig.stagingFormat,
+                                    activeDbPath: getLadybugDbPath(),
+                                    repoRoot: repoRow.rootPath,
+                                    repoConfigJson: repoRow.configJson,
+                                    rows: materializedRows,
+                                }));
+                                shadowBuild.activationResult =
+                                    summarizeProviderFirstShadowActivationReadiness({
+                                        shadowBuild,
+                                        fallbackFiles: 0,
+                                        graphDerivedStateReady: providerFirstSkipDerivedStateReason === undefined,
+                                        shadowContainsFinalizedGraph: false,
+                                        finalizedGraphReasons: providerFirstSkipDerivedStateReason
+                                            ? [providerFirstSkipDerivedStateReason]
+                                            : undefined,
+                                    });
+                                if (shadowBuild.status === "staged") {
+                                    const stagedTotal = providerFirstShadowStageTotal(shadowBuild.counts);
+                                    emitProviderFirstProgress(onProgress, "shadowStage", {
+                                        stageCurrent: stagedTotal,
+                                        stageTotal: stagedTotal,
+                                        message: "provider rows staged for shadow bulk load",
+                                    });
+                                }
                             }
                         }
-                    }
-                    const activeProviderInputHash = scopedSourceFileListActive || providerFirstIncrementalActive
-                        ? null
-                        : "generatedIndexes" in providerResult
-                            ? providerFirstActiveInputFingerprint(providerResult.generatedIndexes)
+                        const activeProviderInputHash = scopedSourceFileListActive || providerFirstIncrementalActive
+                            ? null
+                            : "generatedIndexes" in providerResult
+                                ? providerFirstActiveInputFingerprint(providerResult.generatedIndexes)
+                                : null;
+                        const activeProviderInputRecord = activeProviderInputHash
+                            ? await ladybugDb.getScipIngestionRecord(conn, repoId, PROVIDER_FIRST_ACTIVE_INPUT_RECORD_PATH)
                             : null;
-                    const activeProviderInputRecord = activeProviderInputHash
-                        ? await ladybugDb.getScipIngestionRecord(conn, repoId, PROVIDER_FIRST_ACTIVE_INPUT_RECORD_PATH)
-                        : null;
-                    const activeProviderInputMatches = Boolean(activeProviderInputHash &&
-                        activeProviderInputRecord?.contentHash ===
-                            activeProviderInputHash &&
-                        activeProviderInputRecord.truncated !== true);
-                    const existingProviderSymbolCount = await countExistingScipProviderSymbols(conn, repoId);
-                    const activeMaterializationPlan = providerFirstIncrementalActive
-                        ? {
-                            deleteExistingFileSymbols: true,
-                            useKnownFreshWriters: true,
-                            writeEdges: true,
-                            reuseExistingProviderRows: false,
-                        }
-                        : resolveProviderFirstActiveMaterializationPlan({
-                            existingProviderFileCount: countExistingProviderPrimaryFiles({
-                                providerFiles: materializedRows.files,
-                                existingByPath: providerScan.existingByPath,
-                            }),
-                            providerSymbolCount: materializedRows.symbols.length,
-                            activeProviderInputMatches,
-                            existingProviderSymbolCount,
-                        });
-                    if (activeMaterializationPlan.reuseExistingProviderRows) {
-                        const deleteTotal = providerFirstMaterializePhaseTotal("deleteFileSymbols", materializedRows, activeMaterializationPlan);
-                        emitProviderFirstProgress(onProgress, "materialize.deleteFileSymbols", {
-                            stageCurrent: 0,
-                            stageTotal: deleteTotal,
-                            message: "provider active stale cleanup skipped for large symbol set",
-                        });
-                        const symbolTotal = providerFirstMaterializePhaseTotal("upsertSymbols", materializedRows, activeMaterializationPlan);
-                        emitProviderFirstProgress(onProgress, "materialize.upsertSymbols", {
-                            stageCurrent: symbolTotal,
-                            stageTotal: symbolTotal,
-                            message: "provider active rows reused for existing large symbol set",
-                        });
-                    }
-                    await measureProviderFirstPhase("materialize", "providerFirstMaterialize", () => {
+                        const activeProviderInputMatches = Boolean(activeProviderInputHash &&
+                            activeProviderInputRecord?.contentHash ===
+                                activeProviderInputHash &&
+                            activeProviderInputRecord.truncated !== true);
+                        const existingProviderSymbolCount = await countExistingScipProviderSymbols(conn, repoId);
+                        const activeMaterializationPlan = providerFirstIncrementalActive
+                            ? {
+                                deleteExistingFileSymbols: true,
+                                useKnownFreshWriters: true,
+                                writeEdges: true,
+                                reuseExistingProviderRows: false,
+                            }
+                            : resolveProviderFirstActiveMaterializationPlan({
+                                existingProviderFileCount: countExistingProviderPrimaryFiles({
+                                    providerFiles: materializedRows.files,
+                                    existingByPath: providerScan.existingByPath,
+                                }),
+                                providerSymbolCount: materializedRows.symbols.length,
+                                activeProviderInputMatches,
+                                existingProviderSymbolCount,
+                            });
                         if (activeMaterializationPlan.reuseExistingProviderRows) {
-                            return Promise.resolve();
+                            const deleteTotal = providerFirstMaterializePhaseTotal("deleteFileSymbols", materializedRows, activeMaterializationPlan);
+                            emitProviderFirstProgress(onProgress, "materialize.deleteFileSymbols", {
+                                stageCurrent: 0,
+                                stageTotal: deleteTotal,
+                                message: "provider active stale cleanup skipped for large symbol set",
+                            });
+                            const symbolTotal = providerFirstMaterializePhaseTotal("upsertSymbols", materializedRows, activeMaterializationPlan);
+                            emitProviderFirstProgress(onProgress, "materialize.upsertSymbols", {
+                                stageCurrent: symbolTotal,
+                                stageTotal: symbolTotal,
+                                message: "provider active rows reused for existing large symbol set",
+                            });
                         }
-                        return withWriteConn(async (conn) => {
-                            if (providerRowsHaveMaterialization(materializedRows)) {
-                                // materializeProviderFacts owns its transaction. Wrapping it
-                                // in another transaction makes large provider-first writes
-                                // crash in LadybugDB's native transaction handling.
-                                await materializeProviderFacts(conn, materializedRows, {
-                                    replaceFileSymbols: true,
-                                    deleteExistingFileSymbols: activeMaterializationPlan.deleteExistingFileSymbols,
-                                    useKnownFreshWriters: activeMaterializationPlan.useKnownFreshWriters,
-                                    writeEdges: activeMaterializationPlan.writeEdges,
-                                    pruneExternalSymbols: !scopedSourceFileListActive &&
-                                        !providerFirstIncrementalActive,
-                                    symbolFtsIndexName: appConfig.semantic?.retrieval?.fts?.indexName,
-                                    measurePhase: async (phaseName, fn) => {
-                                        const substage = `materialize.${phaseName}`;
-                                        const phaseTotal = providerFirstMaterializePhaseTotal(phaseName, materializedRows, activeMaterializationPlan);
-                                        emitProviderFirstProgress(onProgress, substage, {
-                                            stageCurrent: 0,
-                                            stageTotal: phaseTotal,
-                                            message: `provider materialize ${phaseName} start`,
-                                        });
-                                        const startedAt = Date.now();
-                                        try {
-                                            return await fn();
-                                        }
-                                        finally {
-                                            recordProviderFirstPhaseTiming(`materialize.${phaseName}`, Date.now() - startedAt);
+                        await measureProviderFirstPhase("materialize", "providerFirstMaterialize", () => {
+                            if (activeMaterializationPlan.reuseExistingProviderRows) {
+                                return Promise.resolve();
+                            }
+                            return withWriteConn(async (conn) => {
+                                if (providerRowsHaveMaterialization(materializedRows)) {
+                                    // materializeProviderFacts owns its transaction. Wrapping it
+                                    // in another transaction makes large provider-first writes
+                                    // crash in LadybugDB's native transaction handling.
+                                    await materializeProviderFacts(conn, materializedRows, {
+                                        replaceFileSymbols: true,
+                                        deleteExistingFileSymbols: activeMaterializationPlan.deleteExistingFileSymbols,
+                                        useKnownFreshWriters: activeMaterializationPlan.useKnownFreshWriters,
+                                        writeEdges: activeMaterializationPlan.writeEdges,
+                                        pruneExternalSymbols: !scopedSourceFileListActive &&
+                                            !providerFirstIncrementalActive,
+                                        symbolFtsIndexName: appConfig.semantic?.retrieval?.fts?.indexName,
+                                        measurePhase: async (phaseName, fn) => {
+                                            const substage = `materialize.${phaseName}`;
+                                            const phaseTotal = providerFirstMaterializePhaseTotal(phaseName, materializedRows, activeMaterializationPlan);
                                             emitProviderFirstProgress(onProgress, substage, {
-                                                stageCurrent: phaseTotal,
+                                                stageCurrent: 0,
                                                 stageTotal: phaseTotal,
-                                                message: `provider materialize ${phaseName} done`,
+                                                message: `provider materialize ${phaseName} start`,
                                             });
-                                        }
-                                    },
-                                });
-                            }
-                            else if (!scopedSourceFileListActive &&
-                                !providerFirstIncrementalActive) {
-                                await ladybugDb.withTransaction(conn, async (txConn) => {
-                                    await ladybugDb.pruneStaleScipExternalSymbols(txConn, repoId, []);
-                                });
-                            }
-                            if (!providerFirstRemovedFilesDeleted &&
-                                providerScan.removedFileIds.length > 0) {
-                                await ladybugDb.withTransaction(conn, async (txConn) => {
-                                    await ladybugDb.deleteFilesByIds(txConn, providerScan.removedFileIds);
-                                });
-                            }
-                            if (activeProviderInputHash) {
-                                await ladybugDb.mergeScipIngestionRecord(conn, {
-                                    id: hashValue({
+                                            const startedAt = Date.now();
+                                            try {
+                                                return await fn();
+                                            }
+                                            finally {
+                                                recordProviderFirstPhaseTiming(`materialize.${phaseName}`, Date.now() - startedAt);
+                                                emitProviderFirstProgress(onProgress, substage, {
+                                                    stageCurrent: phaseTotal,
+                                                    stageTotal: phaseTotal,
+                                                    message: `provider materialize ${phaseName} done`,
+                                                });
+                                            }
+                                        },
+                                    });
+                                }
+                                else if (!scopedSourceFileListActive &&
+                                    !providerFirstIncrementalActive) {
+                                    await ladybugDb.withTransaction(conn, async (txConn) => {
+                                        await ladybugDb.pruneStaleScipExternalSymbols(txConn, repoId, []);
+                                    });
+                                }
+                                if (!providerFirstRemovedFilesDeleted &&
+                                    providerScan.removedFileIds.length > 0) {
+                                    await ladybugDb.withTransaction(conn, async (txConn) => {
+                                        await ladybugDb.deleteFilesByIds(txConn, providerScan.removedFileIds);
+                                    });
+                                }
+                                if (activeProviderInputHash) {
+                                    await ladybugDb.mergeScipIngestionRecord(conn, {
+                                        id: hashValue({
+                                            repoId,
+                                            indexPath: PROVIDER_FIRST_ACTIVE_INPUT_RECORD_PATH,
+                                        }),
                                         repoId,
                                         indexPath: PROVIDER_FIRST_ACTIVE_INPUT_RECORD_PATH,
-                                    }),
-                                    repoId,
-                                    indexPath: PROVIDER_FIRST_ACTIVE_INPUT_RECORD_PATH,
-                                    contentHash: activeProviderInputHash,
-                                    ingestedAt: new Date().toISOString(),
-                                    ledgerVersion: providerResult.generationId,
-                                    symbolCount: materializedRows.symbols.length,
-                                    edgeCount: activeMaterializationPlan.writeEdges
-                                        ? materializedRows.edges.length
-                                        : 0,
-                                    externalSymbolCount: materializedRows.externalSymbols.length,
-                                    truncated: !activeMaterializationPlan.writeEdges,
-                                });
+                                        contentHash: activeProviderInputHash,
+                                        ingestedAt: new Date().toISOString(),
+                                        ledgerVersion: providerResult.generationId,
+                                        symbolCount: materializedRows.symbols.length,
+                                        edgeCount: activeMaterializationPlan.writeEdges
+                                            ? materializedRows.edges.length
+                                            : 0,
+                                        externalSymbolCount: materializedRows.externalSymbols.length,
+                                        truncated: !activeMaterializationPlan.writeEdges,
+                                    });
+                                }
+                            }, postIndexSessionTimeoutMs);
+                        });
+                        invalidateIndexResultCaches(repoId);
+                        providerFirstScipMaterialized = true;
+                        if (activeMaterializationPlan.reuseExistingProviderRows) {
+                            providerFirstMaterializedFiles = 0;
+                            providerFirstMaterializedSymbols = 0;
+                            providerFirstMaterializedEdges = 0;
+                        }
+                        else {
+                            providerFirstMaterializedFiles = materializedRows.files.length;
+                            providerFirstMaterializedSymbols =
+                                materializedRows.symbols.length +
+                                    materializedRows.externalSymbols.length;
+                            providerFirstMaterializedEdges = materializedRows.edges.length;
+                            for (const fileId of materializedRows.changedFileIds) {
+                                providerFirstChangedFileIds.add(fileId);
                             }
-                        }, postIndexSessionTimeoutMs);
-                    });
-                    invalidateIndexResultCaches(repoId);
-                    providerFirstScipMaterialized = true;
-                    if (activeMaterializationPlan.reuseExistingProviderRows) {
-                        providerFirstMaterializedFiles = 0;
-                        providerFirstMaterializedSymbols = 0;
-                        providerFirstMaterializedEdges = 0;
-                    }
-                    else {
-                        providerFirstMaterializedFiles = materializedRows.files.length;
-                        providerFirstMaterializedSymbols =
-                            materializedRows.symbols.length +
-                                materializedRows.externalSymbols.length;
-                        providerFirstMaterializedEdges = materializedRows.edges.length;
-                        for (const fileId of materializedRows.changedFileIds) {
-                            providerFirstChangedFileIds.add(fileId);
                         }
-                    }
-                    const executionReasons = [...coverageReport.reasons];
-                    if (scanScopedProvider.ignoredProviderPaths.length > 0) {
-                        const sample = scanScopedProvider.ignoredProviderPaths
-                            .slice(0, 5)
-                            .join(", ");
-                        executionReasons.push(`SCIP provider ignored ${scanScopedProvider.ignoredProviderPaths.length} repo-relative file(s) outside the configured scan scope: ${sample}`);
-                    }
-                    if (activeMaterializationPlan.reuseExistingProviderRows) {
-                        executionReasons.push(`active provider rows reused for ${materializedRows.symbols.length} large existing symbol row(s); clean rebuild or shadow activation is required to physically retire stale provider rows`);
-                    }
-                    if (scopedSourceFileListActive) {
-                        executionReasons.push("repo.sourceFileListPath is set; provider-first active row reuse and shadow activation are disabled so this subset run cannot masquerade as a complete graph");
-                    }
-                    if (coverageReport.fallbackPaths.size > 0) {
-                        if (legacyFallbackPlan.runLegacyFallback) {
-                            executionReasons.push(`legacy fallback indexed ${legacyFallbackPlan.parsedFiles} uncovered or provider-unusable file(s) after provider-first materialization`);
+                        const executionReasons = [...coverageReport.reasons];
+                        if (scanScopedProvider.ignoredProviderPaths.length > 0) {
+                            const sample = scanScopedProvider.ignoredProviderPaths
+                                .slice(0, 5)
+                                .join(", ");
+                            executionReasons.push(`SCIP provider ignored ${scanScopedProvider.ignoredProviderPaths.length} repo-relative file(s) outside the configured scan scope: ${sample}`);
                         }
-                        if (skippedLegacyFallbackReason) {
-                            executionReasons.push(skippedLegacyFallbackReason);
+                        if (activeMaterializationPlan.reuseExistingProviderRows) {
+                            executionReasons.push(`active provider rows reused for ${materializedRows.symbols.length} large existing symbol row(s); clean rebuild or shadow activation is required to physically retire stale provider rows`);
                         }
-                    }
-                    const coverageSummary = {
-                        ...coverageReport.summary,
-                        fallbackFiles: legacyFallbackPlan.parsedFiles,
-                    };
-                    if (legacyFallbackPlan.skippedFiles > 0) {
-                        coverageSummary.legacyFallbackSkippedFiles =
-                            legacyFallbackPlan.skippedFiles;
-                        coverageSummary.legacyFallbackFileLimit =
-                            legacyFallbackPlan.fileLimit;
-                        if (legacyFallbackPlan.semanticEligibleFallbackFiles !== undefined &&
-                            legacyFallbackPlan.semanticEligibleFileLimit !== undefined) {
-                            coverageSummary.semanticEligibleFallbackFiles =
-                                legacyFallbackPlan.semanticEligibleFallbackFiles;
-                            coverageSummary.semanticEligibleFallbackFileLimit =
-                                legacyFallbackPlan.semanticEligibleFileLimit;
+                        if (scopedSourceFileListActive) {
+                            executionReasons.push("repo.sourceFileListPath is set; provider-first active row reuse and shadow activation are disabled so this subset run cannot masquerade as a complete graph");
                         }
-                    }
-                    if (scanScopedProvider.ignoredProviderPaths.length > 0) {
-                        coverageSummary.ignoredProviderFiles =
-                            scanScopedProvider.ignoredProviderPaths.length;
-                        coverageSummary.ignoredProviderFileSamples =
-                            scanScopedProvider.ignoredProviderPaths.slice(0, 5);
-                    }
-                    providerFirstExecutedSummary = {
-                        ...providerResult.summary,
-                        filesProcessed: materializedRows.files.length,
-                        symbolsIndexed: materializedRows.symbols.length +
-                            materializedRows.externalSymbols.length,
-                        edgesCreated: materializedRows.edges.length,
-                        externalSymbolsIndexed: materializedRows.externalSymbols.length,
-                        shadowBuild,
-                        coverage: coverageSummary,
-                        reasons: executionReasons,
-                    };
-                    if (legacyFallbackPlan.runLegacyFallback) {
-                        logger.info("indexRepo: provider-first materialized; using legacy fallback for uncovered files", {
-                            repoId,
+                        if (coverageReport.fallbackPaths.size > 0) {
+                            if (legacyFallbackPlan.runLegacyFallback) {
+                                executionReasons.push(`legacy fallback indexed ${legacyFallbackPlan.parsedFiles} uncovered or provider-unusable file(s) after provider-first materialization`);
+                            }
+                            if (skippedLegacyFallbackReason) {
+                                executionReasons.push(skippedLegacyFallbackReason);
+                            }
+                        }
+                        const coverageSummary = {
+                            ...coverageReport.summary,
                             fallbackFiles: legacyFallbackPlan.parsedFiles,
-                            reasons: executionReasons,
-                        });
-                        providerFirstScan = filterProviderFirstFallbackScan(providerScan, legacyFallbackPaths);
-                        for (const file of providerFirstScan.files) {
-                            providerFirstFallbackPaths.add(file.path);
+                        };
+                        if (legacyFallbackPlan.skippedFiles > 0) {
+                            coverageSummary.legacyFallbackSkippedFiles =
+                                legacyFallbackPlan.skippedFiles;
+                            coverageSummary.legacyFallbackFileLimit =
+                                legacyFallbackPlan.fileLimit;
+                            if (legacyFallbackPlan.semanticEligibleFallbackFiles !== undefined &&
+                                legacyFallbackPlan.semanticEligibleFileLimit !== undefined) {
+                                coverageSummary.semanticEligibleFallbackFiles =
+                                    legacyFallbackPlan.semanticEligibleFallbackFiles;
+                                coverageSummary.semanticEligibleFallbackFileLimit =
+                                    legacyFallbackPlan.semanticEligibleFileLimit;
+                            }
                         }
-                        providerFirstLegacyFallbackComplete =
-                            isProviderFirstLegacyFallbackPlanComplete(legacyFallbackPlan);
-                        providerFirstLegacyFallbackFileCount =
-                            legacyFallbackPlan.parsedFiles;
-                        providerFirstLegacyFallbackSamplePaths = [
-                            ...legacyFallbackPaths,
-                        ].slice(0, 10);
-                        providerFirstLegacyFallbackStartedAt = Date.now();
-                    }
-                    else {
-                        if (activeMaterializationPlan.reuseExistingProviderRows) {
-                            const versionId = await resolveActiveGraphVersionId("Provider-first SCIP active rows reused");
-                            let semanticDeferred = await markProviderFirstSemanticReadinessDeferred({
+                        if (scanScopedProvider.ignoredProviderPaths.length > 0) {
+                            coverageSummary.ignoredProviderFiles =
+                                scanScopedProvider.ignoredProviderPaths.length;
+                            coverageSummary.ignoredProviderFileSamples =
+                                scanScopedProvider.ignoredProviderPaths.slice(0, 5);
+                        }
+                        providerFirstExecutedSummary = {
+                            ...providerResult.summary,
+                            filesProcessed: materializedRows.files.length,
+                            symbolsIndexed: materializedRows.symbols.length +
+                                materializedRows.externalSymbols.length,
+                            edgesCreated: materializedRows.edges.length,
+                            externalSymbolsIndexed: materializedRows.externalSymbols.length,
+                            shadowBuild,
+                            coverage: coverageSummary,
+                            reasons: executionReasons,
+                        };
+                        if (legacyFallbackPlan.runLegacyFallback) {
+                            logger.info("indexRepo: provider-first materialized; using legacy fallback for uncovered files", {
                                 repoId,
-                                versionId,
-                                appConfig,
-                            });
-                            const semanticRefresh = await runProviderFirstDeferredSemanticRefresh({
-                                versionId,
-                                semanticDeferred,
+                                fallbackFiles: legacyFallbackPlan.parsedFiles,
+                                reasons: executionReasons,
                             });
-                            semanticDeferred = semanticRefresh.semanticDeferred;
-                            providerFirstExecutedSummary = withProviderFirstPhaseTimings(providerFirstExecutedSummary);
-                            const resultScip = "generatedIndexes" in providerResult
+                            providerFirstScan = filterProviderFirstFallbackScan(providerScan, legacyFallbackPaths);
+                            for (const file of providerFirstScan.files) {
+                                providerFirstFallbackPaths.add(file.path);
+                            }
+                            providerFirstLegacyFallbackComplete =
+                                isProviderFirstLegacyFallbackPlanComplete(legacyFallbackPlan);
+                            providerFirstLegacyFallbackFileCount =
+                                legacyFallbackPlan.parsedFiles;
+                            providerFirstLegacyFallbackSamplePaths = [
+                                ...legacyFallbackPaths,
+                            ].slice(0, 10);
+                            providerFirstLegacyFallbackStartedAt = Date.now();
+                        }
+                        else {
+                            if (activeMaterializationPlan.reuseExistingProviderRows) {
+                                const versionId = await resolveActiveGraphVersionId("Provider-first SCIP active rows reused");
+                                let semanticDeferred = await markProviderFirstSemanticReadinessDeferred({
+                                    repoId,
+                                    versionId,
+                                    appConfig,
+                                });
+                                const semanticRefresh = await runProviderFirstDeferredSemanticRefresh({
+                                    versionId,
+                                    semanticDeferred,
+                                });
+                                semanticDeferred = semanticRefresh.semanticDeferred;
+                                providerFirstExecutedSummary = withProviderFirstPhaseTimings(providerFirstExecutedSummary);
+                                const resultScip = "generatedIndexes" in providerResult
+                                    ? {
+                                        generatedIndexes: providerResult.generatedIndexes,
+                                        failures: providerResult.failures,
+                                        generatorCache: activeScipPreRefresh?.cache,
+                                    }
+                                    : undefined;
+                                const result = {
+                                    versionId,
+                                    filesProcessed: 0,
+                                    changedFiles: 0,
+                                    removedFiles: 0,
+                                    symbolsIndexed: 0,
+                                    edgesCreated: 0,
+                                    clustersComputed: 0,
+                                    processesTraced: 0,
+                                    durationMs: Date.now() - startTime,
+                                    pass1Engine: emptyPass1EngineTelemetry(),
+                                    scip: resultScip,
+                                    providerFirst,
+                                    providerFirstExecution: providerFirstExecutedSummary,
+                                    semanticDeferred: semanticDeferred || undefined,
+                                    algorithmRefresh: skippedDerivedStateResult("provider-first active rows reused").algorithmRefresh,
+                                };
+                                clearProviderGraphRowsForGc(materializedRows);
+                                return result;
+                            }
+                            const versionId = await createOrReuseVersion(providerFirstLspExecutor(providerResult.summary.executor)
+                                ? providerFirstIncrementalActive
+                                    ? "Provider-first LSP incremental index"
+                                    : "Provider-first LSP index"
+                                : providerFirstIncrementalActive
+                                    ? "Provider-first SCIP incremental index"
+                                    : "Provider-first SCIP index", true);
+                            const pass1Engine = emptyPass1EngineTelemetry();
+                            const scip = "generatedIndexes" in providerResult
                                 ? {
                                     generatedIndexes: providerResult.generatedIndexes,
                                     failures: providerResult.failures,
                                     generatorCache: activeScipPreRefresh?.cache,
                                 }
                                 : undefined;
+                            const post = await runPostIndexFinalization({
+                                versionId,
+                                indexMode: providerFirstIncrementalActive ? "incremental" : "full",
+                                filesTotal: providerFirstIncrementalActive
+                                    ? providerCoverageScan.files.length
+                                    : materializedRows.files.length,
+                                filesScanned: materializedRows.files.length,
+                                symbolsExtracted: materializedRows.symbols.length +
+                                    materializedRows.externalSymbols.length,
+                                edgesExtracted: materializedRows.edges.length,
+                                changedFileIdsForFinalize: scopedSourceFileListActive || providerFirstIncrementalActive
+                                    ? materializedRows.changedFileIds
+                                    : undefined,
+                                changedTestFilePathsForFinalize: new Set(),
+                                changedFileIdsForMemory: materializedRows.changedFileIds,
+                                hasIndexMutations: true,
+                                callResolutionTelemetry: createCallResolutionTelemetry({
+                                    repoId,
+                                    mode: providerFirstIncrementalActive ? "incremental" : "full",
+                                    pass2EligibleFileCount: 0,
+                                    registeredResolvers: [],
+                                }),
+                                pass1Engine,
+                                scip,
+                                preloadedFileSummarySymbolFactsByFile: buildPreloadedFileSummarySymbolFactsFromRows({
+                                    files: materializedRows.files,
+                                    symbols: materializedRows.symbols,
+                                }),
+                                deferSemanticRefresh: true,
+                                skipDerivedStateReason: providerFirstSkipDerivedStateReason,
+                            });
+                            providerFirstExecutedSummary = {
+                                ...providerFirstExecutedSummary,
+                                shadowBuild: await finalizeProviderFirstShadowBuild(providerFirstExecutedSummary.shadowBuild, versionId, post.semanticDeferred),
+                            };
+                            const semanticRefresh = await runProviderFirstDeferredSemanticRefresh({
+                                versionId,
+                                semanticDeferred: post.semanticDeferred,
+                            });
+                            providerFirstExecutedSummary = withProviderFirstPhaseTimings(providerFirstExecutedSummary);
                             const result = {
                                 versionId,
-                                filesProcessed: 0,
-                                changedFiles: 0,
-                                removedFiles: 0,
-                                symbolsIndexed: 0,
-                                edgesCreated: 0,
-                                clustersComputed: 0,
-                                processesTraced: 0,
+                                filesProcessed: materializedRows.files.length,
+                                changedFiles: materializedRows.changedFileIds.size,
+                                removedFiles: providerScan.removedFiles,
+                                symbolsIndexed: materializedRows.symbols.length +
+                                    materializedRows.externalSymbols.length,
+                                edgesCreated: materializedRows.edges.length,
+                                clustersComputed: post.clustersComputed,
+                                processesTraced: post.processesTraced,
                                 durationMs: Date.now() - startTime,
-                                pass1Engine: emptyPass1EngineTelemetry(),
-                                scip: resultScip,
+                                summaryStats: semanticRefresh.summaryStats ?? post.summaryStats,
+                                timings: phaseTimings
+                                    ? {
+                                        totalMs: Date.now() - startTime,
+                                        phases: phaseTimings,
+                                    }
+                                    : undefined,
+                                pass1Engine,
+                                scip,
                                 providerFirst,
                                 providerFirstExecution: providerFirstExecutedSummary,
-                                semanticDeferred: semanticDeferred || undefined,
-                                algorithmRefresh: skippedDerivedStateResult("provider-first active rows reused").algorithmRefresh,
+                                semanticDeferred: semanticRefresh.semanticDeferred,
+                                algorithmRefresh: post.algorithmRefresh,
                             };
-                            clearProviderGraphRowsForGc(materializedRows);
                             return result;
                         }
-                        const versionId = await createOrReuseVersion(providerFirstLspExecutor(providerResult.summary.executor)
-                            ? providerFirstIncrementalActive
-                                ? "Provider-first LSP incremental index"
-                                : "Provider-first LSP index"
-                            : providerFirstIncrementalActive
-                                ? "Provider-first SCIP incremental index"
-                                : "Provider-first SCIP index", true);
-                        const pass1Engine = emptyPass1EngineTelemetry();
-                        const scip = "generatedIndexes" in providerResult
-                            ? {
-                                generatedIndexes: providerResult.generatedIndexes,
-                                failures: providerResult.failures,
-                                generatorCache: activeScipPreRefresh?.cache,
-                            }
-                            : undefined;
-                        const post = await runPostIndexFinalization({
-                            versionId,
-                            indexMode: providerFirstIncrementalActive ? "incremental" : "full",
-                            filesTotal: providerFirstIncrementalActive
-                                ? providerCoverageScan.files.length
-                                : materializedRows.files.length,
-                            filesScanned: materializedRows.files.length,
-                            symbolsExtracted: materializedRows.symbols.length +
-                                materializedRows.externalSymbols.length,
-                            edgesExtracted: materializedRows.edges.length,
-                            changedFileIdsForFinalize: scopedSourceFileListActive || providerFirstIncrementalActive
-                                ? materializedRows.changedFileIds
-                                : undefined,
-                            changedTestFilePathsForFinalize: new Set(),
-                            changedFileIdsForMemory: materializedRows.changedFileIds,
-                            hasIndexMutations: true,
-                            callResolutionTelemetry: createCallResolutionTelemetry({
-                                repoId,
-                                mode: providerFirstIncrementalActive ? "incremental" : "full",
-                                pass2EligibleFileCount: 0,
-                                registeredResolvers: [],
-                            }),
-                            pass1Engine,
-                            scip,
-                            preloadedFileSummarySymbolFactsByFile: buildPreloadedFileSummarySymbolFactsFromRows({
-                                files: materializedRows.files,
-                                symbols: materializedRows.symbols,
-                            }),
-                            deferSemanticRefresh: true,
-                            skipDerivedStateReason: providerFirstSkipDerivedStateReason,
-                        });
-                        providerFirstExecutedSummary = {
-                            ...providerFirstExecutedSummary,
-                            shadowBuild: await finalizeProviderFirstShadowBuild(providerFirstExecutedSummary.shadowBuild, versionId, post.semanticDeferred),
-                        };
-                        const semanticRefresh = await runProviderFirstDeferredSemanticRefresh({
-                            versionId,
-                            semanticDeferred: post.semanticDeferred,
-                        });
-                        providerFirstExecutedSummary = withProviderFirstPhaseTimings(providerFirstExecutedSummary);
-                        const result = {
-                            versionId,
-                            filesProcessed: materializedRows.files.length,
-                            changedFiles: materializedRows.changedFileIds.size,
-                            removedFiles: providerScan.removedFiles,
-                            symbolsIndexed: materializedRows.symbols.length +
-                                materializedRows.externalSymbols.length,
-                            edgesCreated: materializedRows.edges.length,
-                            clustersComputed: post.clustersComputed,
-                            processesTraced: post.processesTraced,
-                            durationMs: Date.now() - startTime,
-                            summaryStats: semanticRefresh.summaryStats ?? post.summaryStats,
-                            timings: phaseTimings
-                                ? {
-                                    totalMs: Date.now() - startTime,
-                                    phases: phaseTimings,
-                                }
-                                : undefined,
-                            pass1Engine,
-                            scip,
-                            providerFirst,
-                            providerFirstExecution: providerFirstExecutedSummary,
-                            semanticDeferred: semanticRefresh.semanticDeferred,
-                            algorithmRefresh: post.algorithmRefresh,
-                        };
-                        return result;
                     }
                 }
             }
         }
+        catch (err) {
+            if (err instanceof ProviderFirstGraphValidationError)
+                throw err;
+            if (providerFirst.requestedMode !== "auto")
+                throw err;
+            const reason = err instanceof Error ? err.message : String(err);
+            const fallbackReason = formatProviderFirstAutoFallbackReason({
+                reason,
+                providerFirstIncrementalActive,
+            });
+            logger.warn("indexRepo: provider-first phase failed (coverage scan or collection), using legacy fallback", { repoId, reason: fallbackReason });
+            providerFirstExecutionFallback = providerFirstFallbackSummary([
+                fallbackReason,
+            ]);
+            // providerFirstScan stays undefined; legacy scanRepoForIndex will run below.
+        }
     }
     const { files, existingByPath, removedFiles, removedFileIds, allFilesUnchanged: scanAllFilesUnchanged, } = providerFirstScan ??
         (await measurePhase("scanRepo", () => scanRepoForIndex({
@@ -2904,6 +2927,11 @@ async function indexRepoImpl(repoId, mode, onProgress, signal, options, scipPreR
                 onProgress,
             }));
             recordFinalizeIndexingSubphaseTimings(finalizeResult.timings);
+            await measurePhase("ensureCriticalSymbolFts", async () => {
+                await ensureCriticalSymbolFtsIndex({
+                    recordTiming: recordIndexSubphaseTiming,
+                });
+            });
             // Refresh read connection again after version/metrics writes.
             freshConn = await getLadybugConn();
             const derivedResult = providerFirstSkipDerivedStateReason