gitnexus 1.6.12 → 1.6.13-rc.2

package/dist/core/run-analyze.js

@@ -10,6 +10,7 @@
  */
 import { detectGraphWriteCollapse } from './index-freshness.js';
 import { resolveFtsDisableReason, getFtsDisabledReason, withExplicitFtsDisablement, FTS_DISABLED_MESSAGE, DEFAULT_GRAPH_CAPABILITY, DEFAULT_VECTOR_SEARCH_CAPABILITY, } from './search/fts-policy.js';
+import { allowsFtsCrashWalPark, buildFtsDirtyStamp, inferNativeAbortSkip, isBoundaryCheckpointFatal, isFtsStagingDirty, resolveFtsWritePlan, shouldRefuseFtsCrashWal, shouldRefuseRepairFtsWhileDirty, shouldStampFtsDirtyPhase, } from './search/fts-crash-marker.js';
 import { PDG_EDGE_TYPES } from './lbug/pdg-emit-sink.js';
 import path from 'path';
 import fs from 'fs/promises';
@@ -33,9 +34,10 @@ import { getFtsIndexes } from './search/fts-schema.js';
 import { applyContentRetention, contentRetentionFromEnvironment, contentRetentionMismatch, ftsProfileForContentRetention, } from './content-retention.js';
 import { cjkSegmentationModeMismatch, getSearchFTSCjkSegmentation, initialiseSearchFTSCjkSegmentation, } from './search/cjk-segmentation.js';
 import { getExtensionCapability, getExtensionCapabilities, getFtsCapability, resolveAnalyzeInstallPolicy, } from './lbug/extension-loader.js';
-import { diagnoseExtensionLoad } from './lbug/extension-load-error.js';
+import { diagnoseExtensionLoad, extractExtensionPath, usesClassifiedLoadRemedy, } from './lbug/extension-load-error.js';
+import { resolveFtsVersionPair } from './lbug/vendored-extension-path.js';
 import { startWalCheckpointDriver, checkpointOnce, } from './lbug/wal-checkpoint-driver.js';
-import { quarantineSidecarsForDirtyRecovery, inspectLbugSidecars, } from './lbug/sidecar-recovery.js';
+import { ftsCrashParkFailureMessage, quarantineSidecarsForDirtyRecovery, inspectLbugSidecars, } from './lbug/sidecar-recovery.js';
 import { getStoragePaths, resolveBranchPlacement, saveMeta, loadMeta, ensureGitNexusIgnored, registerRepo, adoptFlatBranchLabel, isReadOnlyFilesystemError, isRepoRegistered, cleanupOldKuzuFiles, reconcileMetadataFiles, ensureStoragePathWritable, isMissingFilesystemError, INDEX_METADATA_FILE, CONTENT_RETENTION_SCHEMA_VERSION, } from '../storage/repo-manager.js';
 import { ANALYZE_FORCE_STORAGE_REQUIREMENTS, ANALYZE_STORAGE_REQUIREMENTS, requireStoragePath, } from '../storage/storage-resolver.js';
 import { DEFAULT_PDG_MAX_FUNCTION_LINES } from './ingestion/cfg/collect.js';
@@ -713,6 +715,10 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
     const existingMeta = loadedMeta
         ? withExplicitFtsDisablement(loadedMeta, ftsDisabledReason)
         : undefined;
+    // KTD6: the dying process writes nothing. Infer skip from the FTS-phase
+    // dirty flag (or a persisted native-abort skipReason) BEFORE later
+    // saveMeta calls overwrite the on-disk phase.
+    const priorFtsNativeAbort = inferNativeAbortSkip(existingMeta?.incrementalInProgress, existingMeta?.capabilities?.fts?.skipReason);
     // Claim a fresh, ownership-validated slot before the pipeline writes caches.
     // A later registry-name collision or pipeline failure can otherwise leave
     // cache files without metadata, which must be treated as unowned on the next
@@ -727,6 +733,7 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
         });
     }
     // ── FTS-only repair path ────────────────────────────────────────────
+    const requestedRepairFts = Boolean(options.repairFts);
     if (options.repairFts &&
         existingMeta &&
         contentRetentionMismatch(existingMeta, contentRetention)) {
@@ -738,13 +745,17 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
             throw new Error('Cannot repair FTS indexes because this repository has not been analyzed yet. ' +
                 'Run `gitnexus analyze` first to create the initial index, then retry `--repair-fts`.');
         }
-        if (existingMeta.incrementalInProgress) {
-            // #2409 / tri-review 4669518496 (R6): a dirty flag means the previous
-            // run died mid-writeback — the graph may be half-written and its WAL
-            // possibly poisoned. This branch returns early, so the dirty-recovery
-            // sidecar quarantine below would never run: repairing FTS now would
-            // open the DB and replay that WAL pre-quarantine, and even a
-            // survivable open would certify FTS over a half-written graph.
+        if (shouldRefuseRepairFtsWhileDirty(existingMeta.incrementalInProgress)) {
+            // #2409 / tri-review 4669518496 (R6): a non-FTS dirty flag means the
+            // previous run died mid-writeback — the graph may be half-written and
+            // its WAL possibly poisoned. This branch returns early, so the
+            // dirty-recovery sidecar quarantine below would never run: repairing
+            // FTS now would open the DB and replay that WAL pre-quarantine, and
+            // even a survivable open would certify FTS over a half-written graph.
+            // An FTS-phase flag with a successful checkpoint is different (KTD4):
+            // the graph-boundary checkpoint already ran, so `--repair-fts` must
+            // stay usable (R8). Missing/failed checkpoint is treated like a
+            // half-written graph.
             throw new Error('Cannot repair FTS indexes: the index is mid-incremental-recovery ' +
                 '(a previous analyze run did not complete cleanly). ' +
                 'Run `gitnexus analyze` first — it recovers the index automatically — ' +
@@ -776,6 +787,18 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
                 'Run `gitnexus analyze` (full) to rebuild from scratch.');
         }
         await ensureWritableStorage();
+        // P1 R8: park a poisoned live WAL before opening. Staging never parks —
+        // the live index next to an unpublished staging file must replay its WAL.
+        const repairDirty = existingMeta.incrementalInProgress;
+        if (shouldRefuseFtsCrashWal(repairDirty, existingMeta.capabilities?.fts)) {
+            const { moved: repairParked, removed: repairRemoved, failed: repairParkFailed, } = await quarantineSidecarsForDirtyRecovery(lbugPath, (message) => log(`   ${message}`));
+            if (repairParkFailed.length > 0) {
+                throw new Error(ftsCrashParkFailureMessage(repairParkFailed[0]));
+            }
+            if (repairParked.length + repairRemoved.length > 0) {
+                log('Parked leftover WAL/shadow from the previous in-place FTS abort before --repair-fts.');
+            }
+        }
         try {
             await initAnalysisLbug(lbugPath);
             // Gate on FTS availability BEFORE touching any index. createSearchFTSIndexes
@@ -803,8 +826,9 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
                 // by re-installing — the file is already present. Route that class to the
                 // classified remedy (install VC++ redist / OpenSSL) instead of the old
                 // "retry the network install" text that trapped the user in a loop.
-                const { kind, remedy } = diagnoseExtensionLoad(rawFtsReason);
-                const remedyTail = kind === 'missing_dependency'
+                const inspectPath = extractExtensionPath(rawFtsReason);
+                const { kind, remedy } = diagnoseExtensionLoad(rawFtsReason, 'FTS', inspectPath, resolveFtsVersionPair(inspectPath));
+                const remedyTail = usesClassifiedLoadRemedy(kind)
                     ? ` ${remedy}`
                     : '. Retry with network access and GITNEXUS_LBUG_EXTENSION_INSTALL=auto to install it, ' +
                         'or pre-install the extension file; run `gitnexus doctor` for live FTS status.';
@@ -813,6 +837,22 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
                     remedyTail);
             }
             progress('fts', 85, 'Repairing search indexes...');
+            // Restamp before CREATE so a second native abort still has in-place
+            // FTS dirty evidence after persist cleared the first stamp.
+            try {
+                const latestBeforeCreate = (await loadMeta(metaDir)) ?? existingMeta;
+                await saveMeta(metaDir, {
+                    ...latestBeforeCreate,
+                    incrementalInProgress: buildFtsDirtyStamp({
+                        prior: latestBeforeCreate.incrementalInProgress,
+                        writePlan: 'in-place',
+                        checkpointSucceeded: true,
+                    }),
+                });
+            }
+            catch (err) {
+                log(`FTS dirty restamp write failed (non-critical, continuing with repair${err instanceof Error ? `: ${err.message}` : ''}).`);
+            }
             const repairFailures = await createSearchFTSIndexes({
                 indexes: ftsIndexes,
                 onIndexStart: options.verbose
@@ -859,6 +899,7 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
                 const latestMeta = (await loadMeta(metaDir)) ?? existingMeta;
                 await saveMeta(metaDir, {
                     ...latestMeta,
+                    incrementalInProgress: undefined,
                     capabilities: {
                         graph: latestMeta.capabilities?.graph ?? DEFAULT_GRAPH_CAPABILITY,
                         fts: { provider: 'ladybugdb-fts', status: 'available' },
@@ -939,10 +980,12 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
             resumedEmbeddingCheckpoint = decision.resumedFrom;
         }
     }
-    // ── Crash recovery: dirty flag forces full rebuild ────────────────
-    // If the previous incremental run set incrementalInProgress and didn't
-    // clear it, the on-disk index may be in a half-state. Cheapest path
-    // back to a known-good index is to wipe + rebuild from scratch.
+    // ── Crash recovery ────────────────────────────────────────────────
+    // A non-FTS dirty flag (or an FTS abort that never checkpointed) still
+    // forces a wipe + rebuild. An in-place FTS abort AFTER a successful
+    // graph-boundary checkpoint (Windows full rebuild, POSIX incremental)
+    // parks the live WAL and keeps the graph. A staging FTS abort never
+    // parks the live WAL — that index must replay its own delta.
     if (existingMeta?.incrementalInProgress) {
         const dirty = existingMeta.incrementalInProgress;
         const dirtyDetails = typeof dirty === 'object'
@@ -967,48 +1010,82 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
                 .filter(Boolean)
                 .join(', ')
             : 'legacy dirty flag';
-        log(
-        // "analyze run", not "incremental run" — since #2099 F1 the flag is a
-        // generic dirty marker written by BOTH writeback branches.
-        'Previous analyze run did not complete cleanly (incrementalInProgress flag set); ' +
-            `last dirty state: ${dirtyDetails}; ` +
-            'forcing full rebuild to restore a known-good index.');
-        options = { ...options, force: true };
-        // Reload meta after clearing the flag in-memory; we still want fileHashes
-        // for the post-rebuild meta carry-over, but force=true ensures the
-        // rebuild path executes.
-        //
-        // #2409 defect 2: the crashed writeback's WAL can be poisoned — replaying
-        // it kills the process natively, and the first DB open of this recovery
-        // run (the embedding-cache preservation open below) happens BEFORE the
-        // rebuild wipe that would discard it. Park the WAL/shadow sidecars aside
-        // now, while nothing is open, so every open in this run is replay-free.
-        // The rebuild wipes the DB regardless, so no committed data is at stake.
-        await ensureWritableStorage();
-        const { removed, failed } = await quarantineSidecarsForDirtyRecovery(lbugPath, log);
-        if (removed.length > 0) {
-            log(`Dirty-state recovery discarded ${removed.map((p) => path.basename(p)).join(', ')} ` +
-                'from the interrupted run (the file could not be moved aside, so its bytes were ' +
-                'removed — post-mortem forensics lost). Recovery proceeds with full embedding ' +
-                'preservation.');
-        }
-        if (failed.length > 0) {
-            // FIX 1 (this shipping review, replacing the tri-review 4669518496
-            // P2-3 drop-shape design): under a persistent lock the old drop-shape
-            // run derived its embedding mode as "drop", ran the WHOLE pipeline,
-            // and then died at the rebuild wipe on the very same handle — wasting
-            // minutes and zeroing embeddings on the way. A possibly-poisoned
-            // sidecar still sits next to the DB (any pre-wipe open would replay it
-            // and die), so failing here, in seconds, with the same actionable
-            // typed error the wipe would eventually throw is strictly better —
-            // and the CLI's LbugWipeError handler already renders it
-            // (recoveryHint 'lbug-wipe-failed'). The message is self-contained
-            // (headline + paths + lock guidance) because serve forwards only
-            // err.message over worker IPC.
-            throw new LbugWipeError(failed, {
-                headline: "Cannot start dirty-state recovery — the interrupted run's LadybugDB sidecars " +
-                    'could neither be moved aside nor removed:',
-            });
+        const persistFtsNativeAbortRecovery = async () => {
+            existingMeta.incrementalInProgress = undefined;
+            existingMeta.capabilities = {
+                ...existingMeta.capabilities,
+                graph: existingMeta.capabilities?.graph ?? DEFAULT_GRAPH_CAPABILITY,
+                fts: {
+                    provider: existingMeta.capabilities?.fts?.provider ?? 'ladybugdb-fts',
+                    status: 'unavailable',
+                    skipReason: 'native-abort',
+                    ...(dirty.writePlan ? { writePlan: dirty.writePlan } : {}),
+                },
+                vectorSearch: existingMeta.capabilities?.vectorSearch ?? DEFAULT_VECTOR_SEARCH_CAPABILITY,
+            };
+            await saveMeta(metaDir, existingMeta);
+        };
+        if (allowsFtsCrashWalPark(dirty)) {
+            log('Previous analyze run aborted during in-place FTS after a successful graph checkpoint ' +
+                `(${dirtyDetails}); parking leftover WAL/shadow so the existing graph can reopen. ` +
+                'Search indexes stay skipped until `gitnexus analyze --repair-fts`.');
+            await ensureWritableStorage();
+            const { failed } = await quarantineSidecarsForDirtyRecovery(lbugPath, (message) => log(`   ${message}`));
+            if (failed.length > 0) {
+                throw new Error(ftsCrashParkFailureMessage(failed[0]));
+            }
+            await persistFtsNativeAbortRecovery();
+        }
+        else if (isFtsStagingDirty(dirty)) {
+            log('Previous analyze run aborted during FTS after a staging writeback ' +
+                `(${dirtyDetails}); leaving the live index WAL in place so the unpublished ` +
+                'staging file can still replay. Not forcing a rebuild.');
+            await persistFtsNativeAbortRecovery();
+        }
+        else {
+            log(
+            // "analyze run", not "incremental run" — since #2099 F1 the flag is a
+            // generic dirty marker written by BOTH writeback branches.
+            'Previous analyze run did not complete cleanly (incrementalInProgress flag set); ' +
+                `last dirty state: ${dirtyDetails}; ` +
+                'forcing full rebuild to restore a known-good index.');
+            options = { ...options, force: true };
+            // Reload meta after clearing the flag in-memory; we still want fileHashes
+            // for the post-rebuild meta carry-over, but force=true ensures the
+            // rebuild path executes.
+            //
+            // #2409 defect 2: the crashed writeback's WAL can be poisoned — replaying
+            // it kills the process natively, and the first DB open of this recovery
+            // run (the embedding-cache preservation open below) happens BEFORE the
+            // rebuild wipe that would discard it. Park the WAL/shadow sidecars aside
+            // now, while nothing is open, so every open in this run is replay-free.
+            // The rebuild wipes the DB regardless, so no committed data is at stake.
+            await ensureWritableStorage();
+            const { removed, failed } = await quarantineSidecarsForDirtyRecovery(lbugPath, log);
+            if (removed.length > 0) {
+                log(`Dirty-state recovery discarded ${removed.map((p) => path.basename(p)).join(', ')} ` +
+                    'from the interrupted run (the file could not be moved aside, so its bytes were ' +
+                    'removed — post-mortem forensics lost). Recovery proceeds with full embedding ' +
+                    'preservation.');
+            }
+            if (failed.length > 0) {
+                // FIX 1 (this shipping review, replacing the tri-review 4669518496
+                // P2-3 drop-shape design): under a persistent lock the old drop-shape
+                // run derived its embedding mode as "drop", ran the WHOLE pipeline,
+                // and then died at the rebuild wipe on the very same handle — wasting
+                // minutes and zeroing embeddings on the way. A possibly-poisoned
+                // sidecar still sits next to the DB (any pre-wipe open would replay it
+                // and die), so failing here, in seconds, with the same actionable
+                // typed error the wipe would eventually throw is strictly better —
+                // and the CLI's LbugWipeError handler already renders it
+                // (recoveryHint 'lbug-wipe-failed'). The message is self-contained
+                // (headline + paths + lock guidance) because serve forwards only
+                // err.message over worker IPC.
+                throw new LbugWipeError(failed, {
+                    headline: "Cannot start dirty-state recovery — the interrupted run's LadybugDB sidecars " +
+                        'could neither be moved aside nor removed:',
+                });
+            }
         }
     }
     // ── pdg-mode flip forces full writeback (#2099 F1) ─────────────────
@@ -1387,6 +1464,9 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
                     stats: existingMeta.stats ?? {},
                     alreadyUpToDate: true,
                     ...(ftsDisabledReason ? { ftsSkipped: true, ftsSkipReason: ftsDisabledReason } : {}),
+                    ...(!ftsDisabledReason && priorFtsNativeAbort
+                        ? { ftsSkipped: true, ftsSkipReason: 'native-abort' }
+                        : {}),
                     isPrimaryBranch: !placement.branch,
                 };
             }
@@ -2242,7 +2322,10 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
                         : undefined,
                 ]
                     .filter((e) => e !== undefined)
-                    .map(({ reason, label }) => diagnoseExtensionLoad(reason, label).remedy);
+                    .map(({ reason, label }) => {
+                    const inspectPath = extractExtensionPath(reason);
+                    return diagnoseExtensionLoad(reason, label, inspectPath, label === 'FTS' ? resolveFtsVersionPair(inspectPath) : undefined).remedy;
+                });
                 log(`Incremental: ${escalationCauses.join('; and ')} — switching to a full DB write ` +
                     `(wipe + bulk COPY) for this run; file-level incremental bookkeeping is unaffected.` +
                     (degradedEffects.length > 0
@@ -2499,12 +2582,6 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
                     await restoreDerivedRels(derivedSnapshot);
                 }
             }
-            // Boundary drain (#2409): checkpoint at the end of the incremental
-            // writeback so the WAL it accumulated never lingers into the FTS and
-            // embedding phases — a later crash leaves only post-checkpoint WAL for
-            // the next open to replay. Near-instant when the periodic driver has
-            // kept up; rides the driver's bounded retry via runCheckpointWithRetry.
-            await checkpointOnce();
         }
         else {
             // ── Full rebuild ───────────────────────────────────────────────
@@ -2518,6 +2595,41 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
                 progress('lbug', pct, msg);
             }, pipelineResult.pdgEmitManifest, pipelineResult.graphEmitManifest, contentRetention);
         }
+        // Converged graph-boundary drain: incremental used to checkpoint here;
+        // full rebuild did not. One site so FTS always starts after a settled
+        // plan (post-escalation `buildPath`) and a recorded checkpoint outcome.
+        const ftsWritePlan = resolveFtsWritePlan(buildPath, lbugPath);
+        let boundaryCheckpointSucceeded = false;
+        try {
+            boundaryCheckpointSucceeded = await checkpointOnce();
+        }
+        catch (error) {
+            if (isBoundaryCheckpointFatal(ftsWritePlan)) {
+                throw error;
+            }
+            const detail = error instanceof Error ? error.message : String(error);
+            log(`Boundary WAL checkpoint failed on the in-place FTS path (best-effort): ${detail}. ` +
+                'Continuing; recovery will treat the graph-boundary checkpoint as unsuccessful.');
+        }
+        if (shouldStampFtsDirtyPhase(ftsWritePlan)) {
+            // Lift the prior-meta precondition: a first-ever in-place run (Windows
+            // full rebuild, or any in-place incremental) must stamp too. Staging
+            // never stamps — an abort there abandons the unpublished file.
+            const latestMeta = (await loadMeta(metaDir)) ?? existingMeta;
+            const base = latestMeta ?? {
+                repoPath,
+                lastCommit: '',
+                indexedAt: new Date().toISOString(),
+            };
+            await saveMeta(metaDir, {
+                ...base,
+                incrementalInProgress: buildFtsDirtyStamp({
+                    prior: base.incrementalInProgress,
+                    writePlan: 'in-place',
+                    checkpointSucceeded: boundaryCheckpointSucceeded,
+                }),
+            });
+        }
         // ── Phase 3: FTS (85–90%) ─────────────────────────────────────────
         // The analyze (write) path owns building the search indexes, so it uses
         // the `auto` install policy (LOAD-first, then one bounded INSTALL) —
@@ -2541,12 +2653,28 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
         let ftsReady = ftsAvailable;
         // Why FTS ended up skipped (#2658 review L2): an explicit opt-out
         // (`disabled-by-flag` / `disabled-by-env`, #3091) when one was recorded,
+        // else tuple-missing when the loader reported no packaged artifact,
         // else extension-unavailable up front, or build-failed in the degrade
         // branch below.
+        const tupleMissing = !ftsAvailable &&
+            !ftsDisabledReason &&
+            /no packaged FTS artifact/i.test(getFtsCapability()?.reason ?? '');
         let ftsSkipReason = ftsAvailable
             ? undefined
-            : (ftsDisabledReason ?? 'extension-unavailable');
-        if (ftsAvailable) {
+            : (ftsDisabledReason ?? (tupleMissing ? 'tuple-missing' : 'extension-unavailable'));
+        if (ftsAvailable && priorFtsNativeAbort && !requestedRepairFts) {
+            // KTD6 / R11: do not retry CREATE_FTS_INDEX after a native abort —
+            // the same content can kill the process again. `--repair-fts` is the
+            // explicit retry: its early-return path never reaches this branch,
+            // and a retention-mismatch rewrite that started as `--repair-fts`
+            // still creates indexes.
+            ftsReady = false;
+            ftsSkipReason = 'native-abort';
+            log('FTS index build skipped — a previous analyze aborted while building search indexes. ' +
+                'Graph analysis completed. Run `gitnexus analyze --repair-fts` to retry.');
+            progress('fts', 90, 'Search indexes skipped (previous native abort)');
+        }
+        else if (ftsAvailable) {
             // Degrade rather than throw: createSearchFTSIndexes re-tokenizes every
             // stored row on every run, so a native tokenizer error on a single
             // pre-existing row (#2544/#2546) must not discard this run's otherwise-
@@ -2598,8 +2726,9 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
             // Same #2383 mock seam as the repair path above — keep the exported
             // `getExtensionCapabilities()` lookup here.
             const ftsReason = getExtensionCapabilities().find((c) => c.name === 'fts')?.reason;
-            const { kind, remedy } = diagnoseExtensionLoad(ftsReason);
-            log(kind === 'missing_dependency'
+            const inspectPath = extractExtensionPath(ftsReason);
+            const { kind, remedy } = diagnoseExtensionLoad(ftsReason, 'FTS', inspectPath, resolveFtsVersionPair(inspectPath));
+            log(usesClassifiedLoadRemedy(kind)
                 ? `${FTS_UNAVAILABLE_LEAD} ${remedy}`
                 : FTS_UNAVAILABLE_MESSAGE);
             progress('fts', 90, 'Search indexes skipped (FTS unavailable)');
@@ -3252,6 +3381,14 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
                     // 'unavailable', and the next run does it again. Stamping the
                     // discriminator the run already computed makes the read exact instead.
                     skipReason: ftsReady ? undefined : ftsSkipReason,
+                    // Keep the abort write plan after persist cleared the dirty flag
+                    // so a leftover live WAL is still refuse-able. Successful FTS
+                    // drops it with skipReason.
+                    ...(!ftsReady &&
+                        ftsSkipReason === 'native-abort' &&
+                        existingMeta?.capabilities?.fts?.writePlan
+                        ? { writePlan: existingMeta.capabilities.fts.writePlan }
+                        : {}),
                 },
                 vectorSearch: {
                     provider: effectiveSemanticMode === 'vector-index' ? 'ladybugdb-vector' : 'exact-scan',

package/dist/core/search/fts-crash-marker.d.ts

@@ -0,0 +1,59 @@
+/**
+ * FTS-phase dirty-flag policy (KTD4 / KTD6).
+ *
+ * A native abort during CREATE_FTS_INDEX kills the process before JS can
+ * persist a skip reason. The next run infers `native-abort` from this phase
+ * value, or from a persisted `capabilities.fts.skipReason` of `native-abort`
+ * after recovery clears the dirty flag. Tests induce the flag through
+ * saveMeta — they cannot be a green real-abort of analyze.
+ */
+import type { RepoMeta } from '../../storage/repo-meta.js';
+export declare const FTS_DIRTY_PHASE: "fts";
+export type FtsWritePlan = 'in-place' | 'staging';
+export type IncrementalDirtyState = NonNullable<RepoMeta['incrementalInProgress']>;
+export declare const resolveFtsWritePlan: (buildPath: string, livePath: string) => FtsWritePlan;
+export declare const shouldStampFtsDirtyPhase: (writePlan: FtsWritePlan) => boolean;
+/** Staging throws (abandons the unpublished file). In-place is best-effort. */
+export declare const isBoundaryCheckpointFatal: (writePlan: FtsWritePlan) => boolean;
+export declare const isFtsDirtyPhase: (dirty: RepoMeta["incrementalInProgress"] | undefined) => dirty is IncrementalDirtyState & {
+    phase: typeof FTS_DIRTY_PHASE;
+};
+/**
+ * Half-written graph, or FTS-phase without a successful checkpoint, blocks
+ * `--repair-fts`. FTS-phase + `checkpointSucceeded === true` is admitted
+ * (in-place or staging). Staging still must not park.
+ */
+export declare const shouldRefuseRepairFtsWhileDirty: (dirty: RepoMeta["incrementalInProgress"] | undefined) => boolean;
+export declare const inferNativeAbortSkip: (dirty: RepoMeta["incrementalInProgress"] | undefined, skipReason?: string) => boolean;
+/**
+ * KTD5 conjunctive warrant for parking a live WAL: FTS phase, in-place
+ * write plan (Windows full rebuild, POSIX incremental, escalated-in-place),
+ * and a successful graph-boundary checkpoint. Staging never qualifies —
+ * the live index next to an unpublished staging file must keep its WAL.
+ */
+export declare const allowsFtsCrashWalPark: (dirty: RepoMeta["incrementalInProgress"] | undefined) => boolean;
+export declare const isInPlaceFtsDirty: (dirty: RepoMeta["incrementalInProgress"] | undefined) => dirty is IncrementalDirtyState & {
+    phase: typeof FTS_DIRTY_PHASE;
+    writePlan: "in-place";
+};
+/** Persisted FTS capability fields used as crash evidence after the dirty flag is cleared. */
+export type PersistedFtsCrashEvidence = {
+    skipReason?: string;
+    writePlan?: FtsWritePlan;
+};
+export declare const hasRecoveredInPlaceFtsAbort: (fts: PersistedFtsCrashEvidence | undefined) => boolean;
+/**
+ * Reader / `--repair-fts` refuse-or-park warrant. Any in-place FTS dirty
+ * flag is enough — a failed graph-boundary checkpoint still leaves CREATE
+ * able to abort with a live WAL. After persist clears the flag, a
+ * `native-abort` skip plus persisted `writePlan: 'in-place'` is the same
+ * evidence. Staging persist also writes `native-abort` and must not match.
+ */
+export declare const shouldRefuseFtsCrashWal: (dirty: RepoMeta["incrementalInProgress"] | undefined, fts?: PersistedFtsCrashEvidence) => boolean;
+export declare const isFtsStagingDirty: (dirty: RepoMeta["incrementalInProgress"] | undefined) => boolean;
+export declare const buildFtsDirtyStamp: (args: {
+    prior?: IncrementalDirtyState;
+    now?: number;
+    writePlan: "in-place";
+    checkpointSucceeded: boolean;
+}) => IncrementalDirtyState;

package/dist/core/search/fts-crash-marker.js

@@ -0,0 +1,55 @@
+export const FTS_DIRTY_PHASE = 'fts';
+export const resolveFtsWritePlan = (buildPath, livePath) => buildPath === livePath ? 'in-place' : 'staging';
+export const shouldStampFtsDirtyPhase = (writePlan) => writePlan === 'in-place';
+/** Staging throws (abandons the unpublished file). In-place is best-effort. */
+export const isBoundaryCheckpointFatal = (writePlan) => writePlan === 'staging';
+export const isFtsDirtyPhase = (dirty) => dirty?.phase === FTS_DIRTY_PHASE;
+/**
+ * Half-written graph, or FTS-phase without a successful checkpoint, blocks
+ * `--repair-fts`. FTS-phase + `checkpointSucceeded === true` is admitted
+ * (in-place or staging). Staging still must not park.
+ */
+export const shouldRefuseRepairFtsWhileDirty = (dirty) => dirty != null && (!isFtsDirtyPhase(dirty) || dirty.checkpointSucceeded !== true);
+export const inferNativeAbortSkip = (dirty, skipReason) => isFtsDirtyPhase(dirty) || skipReason === 'native-abort';
+/**
+ * KTD5 conjunctive warrant for parking a live WAL: FTS phase, in-place
+ * write plan (Windows full rebuild, POSIX incremental, escalated-in-place),
+ * and a successful graph-boundary checkpoint. Staging never qualifies —
+ * the live index next to an unpublished staging file must keep its WAL.
+ */
+export const allowsFtsCrashWalPark = (dirty) => isFtsDirtyPhase(dirty) && dirty.writePlan === 'in-place' && dirty.checkpointSucceeded === true;
+export const isInPlaceFtsDirty = (dirty) => isFtsDirtyPhase(dirty) && dirty.writePlan === 'in-place';
+export const hasRecoveredInPlaceFtsAbort = (fts) => fts?.skipReason === 'native-abort' && fts.writePlan === 'in-place';
+/**
+ * Reader / `--repair-fts` refuse-or-park warrant. Any in-place FTS dirty
+ * flag is enough — a failed graph-boundary checkpoint still leaves CREATE
+ * able to abort with a live WAL. After persist clears the flag, a
+ * `native-abort` skip plus persisted `writePlan: 'in-place'` is the same
+ * evidence. Staging persist also writes `native-abort` and must not match.
+ */
+export const shouldRefuseFtsCrashWal = (dirty, fts) => isInPlaceFtsDirty(dirty) || hasRecoveredInPlaceFtsAbort(fts);
+export const isFtsStagingDirty = (dirty) => isFtsDirtyPhase(dirty) && dirty.writePlan === 'staging';
+export const buildFtsDirtyStamp = (args) => {
+    const now = args.now ?? Date.now();
+    const prior = args.prior;
+    return {
+        startedAt: prior?.startedAt ?? now,
+        updatedAt: now,
+        toWriteCount: prior?.toWriteCount ?? 0,
+        phase: FTS_DIRTY_PHASE,
+        writePlan: args.writePlan,
+        checkpointSucceeded: args.checkpointSucceeded,
+        ...(prior?.directWriteCount !== undefined ? { directWriteCount: prior.directWriteCount } : {}),
+        ...(prior?.importerExpansion !== undefined
+            ? { importerExpansion: prior.importerExpansion }
+            : {}),
+        ...(prior?.effectiveWriteCount !== undefined
+            ? { effectiveWriteCount: prior.effectiveWriteCount }
+            : {}),
+        ...(prior?.deleteCount !== undefined ? { deleteCount: prior.deleteCount } : {}),
+        ...(prior?.shadowSeedCount !== undefined ? { shadowSeedCount: prior.shadowSeedCount } : {}),
+        ...(prior?.droppedImporterChunks !== undefined
+            ? { droppedImporterChunks: prior.droppedImporterChunks }
+            : {}),
+    };
+};

package/dist/core/search/fts-indexes.js

@@ -1,7 +1,7 @@
 import { createFTSIndex, dropFTSIndex, indexRowName, indexRowTable, resolveGateRows, DEFAULT_FTS_STEMMER, } from '../lbug/lbug-adapter.js';
 import { getFtsCapability } from '../lbug/extension-loader.js';
 import { FTS_DISABLED_MESSAGE } from './fts-policy.js';
-import { classifyExtensionLoadError } from '../lbug/extension-load-error.js';
+import { classifyExtensionLoadError, usesClassifiedLoadRemedy, } from '../lbug/extension-load-error.js';
 import { FTS_INDEXES } from './fts-schema.js';
 /**
  * Strip filesystem paths from a LadybugDB error before it reaches the HTTP
@@ -59,7 +59,7 @@ export const ftsDegradedWarning = (context, disabledReason) => {
         // per-request path (HTTP /api/search + MCP query) does NO file I/O (#2383 F3);
         // fall back to the pure, no-I/O string classifier if it is somehow absent.
         const { kind, remedy } = fts.diagnosis ?? classifyExtensionLoadError(fts.reason);
-        const tail = kind === 'missing_dependency'
+        const tail = usesClassifiedLoadRemedy(kind)
             ? ` ${remedy}`
             : '. Run `gitnexus doctor` for details, then `gitnexus analyze --repair-fts` with network access to reinstall.';
         return ('FTS extension failed to load — keyword search degraded' +

package/dist/core/search/fts-policy.d.ts

@@ -1,6 +1,11 @@
 import type { RepoMeta } from '../../storage/repo-meta.js';
 export type FtsDisabledReason = 'disabled-by-flag' | 'disabled-by-env';
-export type FtsSkipReason = FtsDisabledReason | 'extension-unavailable' | 'build-failed';
+/** Failure-like skip reasons. Must not join `FtsDisabledReason` — that
+ *  predicate is a hand-written `string` check the compiler does not verify. */
+export type FtsFailureSkipReason = 'extension-unavailable' | 'build-failed' | 'native-abort' | 'tuple-missing';
+export type FtsSkipReason = FtsDisabledReason | FtsFailureSkipReason;
+/** Runtime list for storage/core parity tests. Order is not significant. */
+export declare const FTS_SKIP_REASONS: readonly FtsSkipReason[];
 type RepoCapabilities = NonNullable<RepoMeta['capabilities']>;
 export declare const DEFAULT_GRAPH_CAPABILITY: RepoCapabilities['graph'];
 export declare const DEFAULT_VECTOR_SEARCH_CAPABILITY: RepoCapabilities['vectorSearch'];
@@ -15,4 +20,9 @@ export declare function getFtsDisabledReason(capability: RepoCapabilities['fts']
  */
 export declare function withExplicitFtsDisablement(meta: RepoMeta, reason: FtsDisabledReason | undefined): RepoMeta;
 export declare const FTS_DISABLED_MESSAGE: string;
+/**
+ * CLI analyze summary copy for a skipped FTS build. Total switch so a new
+ * member cannot silently inherit the network-install remedy.
+ */
+export declare const formatAnalyzeFtsSkipSummary: (reason: FtsSkipReason | undefined) => string;
 export {};

package/dist/core/search/fts-policy.js

@@ -1,3 +1,14 @@
+const _ftsSkipReasonStorageParity = true;
+void _ftsSkipReasonStorageParity;
+/** Runtime list for storage/core parity tests. Order is not significant. */
+export const FTS_SKIP_REASONS = [
+    'disabled-by-flag',
+    'disabled-by-env',
+    'extension-unavailable',
+    'build-failed',
+    'native-abort',
+    'tuple-missing',
+];
 export const DEFAULT_GRAPH_CAPABILITY = {
     provider: 'ladybugdb',
     status: 'available',
@@ -54,3 +65,39 @@ export function withExplicitFtsDisablement(meta, reason) {
 }
 export const FTS_DISABLED_MESSAGE = 'FTS disabled for this index. To enable keyword search, run gitnexus analyze ' +
     'without --skip-fts and with GITNEXUS_SKIP_FTS unset.';
+const FTS_BUILD_FAILED_MESSAGE = 'Warning: full-text/BM25 search is disabled — the search index build failed this run.\n' +
+    '  The FTS extension is available; rerun `gitnexus analyze --repair-fts`. If it persists,\n' +
+    '  check the disk for space or corruption. Run `gitnexus doctor` for details.';
+const FTS_EXTENSION_UNAVAILABLE_MESSAGE = 'Warning: full-text/BM25 search is disabled — the LadybugDB FTS extension was unavailable.\n' +
+    '  Install it once with network access (GITNEXUS_LBUG_EXTENSION_INSTALL=auto), then run\n' +
+    '  `gitnexus analyze --repair-fts` to build the search indexes. Run `gitnexus doctor` for details.';
+const FTS_NATIVE_ABORT_MESSAGE = 'Warning: full-text/BM25 search is disabled — a previous analyze aborted while building the search indexes.\n' +
+    '  Rerun `gitnexus analyze --repair-fts` to recover. Run `gitnexus doctor` for details.';
+const FTS_TUPLE_MISSING_MESSAGE = 'Warning: full-text/BM25 search is disabled — no packaged FTS artifact is available for this platform.\n' +
+    '  Keyword search is unavailable on this host. Run `gitnexus doctor` for details.';
+const assertNever = (value) => {
+    throw new Error(`unhandled FTS skip reason: ${String(value)}`);
+};
+/**
+ * CLI analyze summary copy for a skipped FTS build. Total switch so a new
+ * member cannot silently inherit the network-install remedy.
+ */
+export const formatAnalyzeFtsSkipSummary = (reason) => {
+    if (reason === undefined)
+        return FTS_EXTENSION_UNAVAILABLE_MESSAGE;
+    switch (reason) {
+        case 'disabled-by-flag':
+        case 'disabled-by-env':
+            return FTS_DISABLED_MESSAGE;
+        case 'build-failed':
+            return FTS_BUILD_FAILED_MESSAGE;
+        case 'native-abort':
+            return FTS_NATIVE_ABORT_MESSAGE;
+        case 'tuple-missing':
+            return FTS_TUPLE_MISSING_MESSAGE;
+        case 'extension-unavailable':
+            return FTS_EXTENSION_UNAVAILABLE_MESSAGE;
+        default:
+            return assertNever(reason);
+    }
+};