knodin 0.10.2 → 0.10.4

package/dist/src/engine/index.js

@@ -28,7 +28,7 @@ import { contentFingerprint, writeStructuralSnapshot, } from "../structural-snap
 import { acquireLifecycleCoordination } from "../update-coordination.js";
 import { KNODIN_VERSION } from "../version.js";
 import * as ann from "./ann-hnsw.js";
-import { allocateCandidate, assertCandidate, discardCandidateFiles, promoteCandidateFile, recoverInterruptedPromotion, } from "./candidate-database.js";
+import { allocateCandidate, assertCandidate, discardCandidateFiles, listCandidates, promoteCandidateFile, recoverInterruptedPromotion, } from "./candidate-database.js";
 import { computeSimilarity, generateEmbedding, generateEmbeddings, } from "./embeddings.js";
 import { walkRepoFiles } from "./file-walker.js";
 import { clearGitHistorySignalCache, collectGitHistorySignals, } from "./git-history.js";
@@ -46,6 +46,7 @@ import { isIndexableSourcePath } from "./source-policy.js";
 import { Database } from "./sqlite.js";
 import { lookupMirror, mayWriteToRepository, resolveDbPath, resolveStateDir, } from "./state-paths.js";
 import { deleteAllSymbols, deleteSymbolsForFile, deleteSymbolsMatchingPath, ORPHANED_EMBEDDING_PREDICATE, purgeOrphanEmbeddings, } from "./symbol-delete.js";
+import { searchRepoText } from "./text-matches.js";
 // ES Module resolution
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -373,6 +374,36 @@ export function extractMcpToolRegistrations(source, file, root) {
 }
 /** `meta` key holding the last index's unparsed-file tally, as a JSON object. */
 export const COVERAGE_UNPARSED_META_KEY = "coverageUnparsedByExtension";
+/**
+ * `meta` key set while a full index is running and cleared when it finishes.
+ *
+ * The tally is written incrementally so an interrupted index does not lose it,
+ * which means a present tally no longer implies a *complete* one. This marker
+ * is what keeps the two apart: while it is set, the tally describes however far
+ * the run got, and `unparsedUnknown` reports it as a lower bound rather than a
+ * measurement.
+ *
+ * Without it, an index killed at 71% would leave a plausible-looking tally that
+ * `status` presents as fact — the precise confusion `unparsedUnknown` exists to
+ * prevent, reintroduced through the back door.
+ */
+export const COVERAGE_TALLY_IN_PROGRESS_META_KEY = "coverageUnparsedIncomplete";
+/**
+ * `meta` keys marking a candidate database as a clean index still in progress.
+ *
+ * A clean index builds into a candidate and promotes it atomically, discarding
+ * it on failure — which is why a partial rebuild can never be observed as the
+ * live graph, and why that behaviour is preserved exactly. But a killed process
+ * runs no discard, so the candidate simply survives on disk, and until now the
+ * next run allocated a fresh one and repeated hours of work.
+ *
+ * These make the survivor recognisable. The marker says "a build was underway";
+ * the head says "of this tree". Both are needed: resuming a build of a tree that
+ * has since moved on would promote a graph that never described any single state
+ * of the repository, which is worse than starting over.
+ */
+export const CLEAN_INDEX_IN_PROGRESS_META_KEY = "cleanIndexInProgress";
+export const CLEAN_INDEX_HEAD_META_KEY = "cleanIndexHead";
 function repairMetadataFamily(filePath) {
     const segments = filePath.replaceAll("\\", "/").split("/");
     const extension = path.extname(filePath).toLowerCase();
@@ -7059,6 +7090,12 @@ function createIndexProgressReporter(onProgress) {
                 elapsedMs: emittedAt - startedAt,
                 message,
                 ...(details.modelFile === undefined ? {} : { modelFile: details.modelFile }),
+                ...(details.phaseBytesCompleted === undefined
+                    ? {}
+                    : { phaseBytesCompleted: details.phaseBytesCompleted }),
+                ...(details.phaseBytesTotal === undefined
+                    ? {}
+                    : { phaseBytesTotal: details.phaseBytesTotal }),
             });
         }
         catch {
@@ -7224,6 +7261,75 @@ function sumCounts(counts) {
  *
  * Still never throws: a status call must not fail because a tally is corrupt.
  */
+/**
+ * A candidate left mid-build that it is safe to continue, or null.
+ *
+ * Deliberately conservative: every uncertainty resolves to "start over", which
+ * costs time, versus resuming onto the wrong tree, which produces a graph that
+ * never described any single state of the repository and then promotes it.
+ *
+ * Stale and unusable candidates are removed as they are found, so a repository
+ * does not accumulate abandoned copies of its own database.
+ */
+function findResumableCandidate(repoPath) {
+    const head = gitHead(repoPath) ?? "";
+    let resumable = null;
+    for (const candidate of listCandidates(repoPath)) {
+        let usable = false;
+        try {
+            const probe = new Database(candidate.databasePath, { readonly: true });
+            try {
+                usable =
+                    getMeta(probe, CLEAN_INDEX_IN_PROGRESS_META_KEY) === "1" &&
+                        getMeta(probe, CLEAN_INDEX_HEAD_META_KEY) === head;
+            }
+            finally {
+                probe.close();
+            }
+        }
+        catch {
+            // Unreadable, not a database, or schema too old to query. Not resumable,
+            // and not worth keeping.
+            usable = false;
+        }
+        // Keep only the newest usable one. An older survivor is from an even
+        // earlier interrupted run and has nothing to add.
+        if (usable && resumable === null) {
+            resumable = candidate;
+            continue;
+        }
+        try {
+            discardCandidateFiles(repoPath, candidate);
+        }
+        catch {
+            // Best effort: failing to clean up a stale candidate must not stop the
+            // rebuild that is about to replace it.
+        }
+    }
+    return resumable;
+}
+/** Write the coverage tally as it stands. Safe to call repeatedly mid-index. */
+function persistUnparsedTally(db, tally) {
+    setMeta(db, COVERAGE_UNPARSED_META_KEY, JSON.stringify(Object.fromEntries(tally)));
+}
+/**
+ * True when the stored tally came from a run that did not finish.
+ *
+ * Read separately from the tally itself because the two answer different
+ * questions: the tally says what was seen, this says whether that is all there
+ * was to see.
+ */
+function unparsedTallyIsIncomplete(db) {
+    if (!db)
+        return false;
+    try {
+        return getMeta(db, COVERAGE_TALLY_IN_PROGRESS_META_KEY) === "1";
+    }
+    catch {
+        // Unreadable meta is not a claim that the tally is complete.
+        return true;
+    }
+}
 function readUnparsedTally(db) {
     if (!db)
         return null;
@@ -7290,6 +7396,10 @@ function worstSemanticReadiness(states) {
 function buildCoverageSkips(skippedByExtension, db) {
     const byExtension = sortedTally(skippedByExtension);
     const unparsed = readUnparsedTally(db);
+    // A tally that exists but came from an unfinished run is as unmeasured as an
+    // absent one: it counts only the files that run happened to reach. Both cases
+    // set `unparsedUnknown`, which downstream already renders as a lower bound.
+    const incomplete = unparsed === null || unparsedTallyIsIncomplete(db);
     return {
         byExtension,
         // Reported as empty when unknown so consumers reading only this field are
@@ -7297,7 +7407,7 @@ function buildCoverageSkips(skippedByExtension, db) {
         // measurement. `total` is then a lower bound, not a count.
         unparsedByExtension: unparsed ?? {},
         total: sumCounts(byExtension) + sumCounts(unparsed ?? {}),
-        ...(unparsed === null ? { unparsedUnknown: true } : {}),
+        ...(incomplete ? { unparsedUnknown: true } : {}),
     };
 }
 /**
@@ -7554,13 +7664,23 @@ function buildFreshnessEnvelope(repoPath, db, verifiedAt, stateOverride, gitProb
  * Snapshot a file's on-disk mtime/size into `index_state`, so a later cold start
  * can tell whether it drifted while no knodin process was watching.
  */
+/**
+ * Record a file's mtime and size, returning the size.
+ *
+ * The size is returned rather than discarded so byte-based progress costs no
+ * extra I/O: this already stats every indexed file, and a second pass over
+ * 900,000 files to learn what it just measured would be pure waste. Returns 0
+ * when the file could not be stat'd, which the caller adds harmlessly.
+ */
 function recordIndexState(db, repoPath, relPath) {
     try {
         const st = fs.statSync(path.join(repoPath, relPath));
         db.run("INSERT INTO index_state(filePath, mtimeMs, size) VALUES (?, ?, ?) ON CONFLICT(filePath) DO UPDATE SET mtimeMs = excluded.mtimeMs, size = excluded.size", [relPath, st.mtimeMs, st.size]);
+        return st.size;
     }
     catch (_) {
         // File vanished between indexing and stat — reconcile-delete handles it.
+        return 0;
     }
 }
 /** Drop a file's `index_state` row (used when a file is deleted). */
@@ -7638,7 +7758,7 @@ function detectDriftByStat(repoPath, db, canonicalFiles) {
     }
     return changed;
 }
-async function reconcileIndex(repoPath, db, progress) {
+async function reconcileIndex(repoPath, db, progress, skipEmbeddings = false) {
     try {
         progress?.("collecting-files", 0, "Checking existing local graph for changes");
         const changed = new Set();
@@ -7757,18 +7877,26 @@ async function reconcileIndex(repoPath, db, progress) {
         // Re-embed ONLY what changed (indexEmbeddings embeds symbols lacking an
         // embedding), so a no-op reconcile triggers no embedding work at all.
         if (reindexed > 0) {
-            progress?.("finalizing", 0, "Refreshing identities and semantic embeddings");
+            progress?.("finalizing", 0, skipEmbeddings
+                ? "Refreshing identities (semantic embeddings deferred)"
+                : "Refreshing identities and semantic embeddings");
             persistSymbolIdentities(db, repoPath, reindexedPaths);
             reconcileTypeScriptDi(db, repoPath);
-            await indexEmbeddings(db, repoPath, progress);
+            if (!skipEmbeddings)
+                await indexEmbeddings(db, repoPath, progress);
             indexGeneration++;
         }
-        else if (semanticReadinessFor(db) !== "ready") {
+        else if (!skipEmbeddings && semanticReadinessFor(db) !== "ready") {
             // Unchanged files do NOT imply current embeddings: a deferred
             // (`skipEmbeddings`) or interrupted pass leaves symbols unembedded while
             // every file looks reconciled. Without this, the follow-up index a user
             // is told to run would do nothing and semantic search would stay
             // silently short forever.
+            //
+            // Which is also why `skipEmbeddings` has to suppress it: this branch
+            // exists to COMPLETE a deferred pass, so leaving it unguarded would make
+            // `--skip-embeddings` a silent no-op on exactly the warm graphs large
+            // enough to want it — the flag would appear to work and do the opposite.
             progress?.("finalizing", 0, "Completing deferred semantic embeddings");
             await indexEmbeddings(db, repoPath, progress);
             indexGeneration++;
@@ -8146,7 +8274,17 @@ function stalenessFor(repoPath) {
     return freshnessProbes.get(path.resolve(repoPath))?.staleness ?? "unknown";
 }
 /** Recursively indexes all matching files within the repository. */
-async function indexRepo(repoPath, db, progress, skipEmbeddings = false, publishProcessState = true) {
+async function indexRepo(repoPath, db, progress, skipEmbeddings = false, publishProcessState = true, 
+/**
+ * Continue a build already in this database instead of starting over.
+ *
+ * Skips the wipe below and skips files whose `index_state` row still matches
+ * disk. Only ever set for a candidate database that a previous run left
+ * mid-build: the live graph is never resumed into, because resuming implies
+ * partially-populated intermediate state and the live graph must never be
+ * observable in that condition.
+ */
+resume = false) {
     progress?.("collecting-files", 0, "Discovering indexable files");
     const collected = measurePerfPhaseSync("file_collection", () => collectRepoFilesWithCoverage(repoPath));
     const files = collected.files;
@@ -8154,15 +8292,82 @@ async function indexRepo(repoPath, db, progress, skipEmbeddings = false, publish
     // during the parse. Persisted below so `status` can report the gap without
     // re-indexing the repository to rediscover it.
     const unparsedByExtension = new Map();
+    // Claim the tally as in-progress BEFORE the first file. An index killed
+    // partway used to leave the previous run's tally in place and reported as
+    // fact; now whatever is stored is flagged a lower bound until this run
+    // finishes and clears the marker.
+    setMeta(db, COVERAGE_TALLY_IN_PROGRESS_META_KEY, "1");
+    // One stat pass to learn the weight of the work before starting it. Counted
+    // separately from files because the two diverge sharply: on a real Salesforce
+    // checkout 0.05% of the files hold 78% of the bytes, so a files-only estimate
+    // is confidently wrong rather than merely rough.
+    //
+    // `size` is a floor on cost, not a proxy for it — a large XML file is not
+    // exactly proportional to a large TypeScript one — but it tracks the actual
+    // shape of the work far better than a file count, which treats a 7 MB profile
+    // and a 200-byte translation as equal.
+    let totalBytes = 0;
+    for (const file of files) {
+        try {
+            totalBytes += fs.statSync(path.join(repoPath, file)).size;
+        }
+        catch {
+            // Unreadable or vanished: it will fail in the loop below too, where the
+            // failure is reported. Excluding it here only makes the total a floor.
+        }
+    }
+    let completedBytes = 0;
     progress?.("indexing-files", 0, `Indexing ${files.length.toLocaleString()} files`, {
         phaseTotal: files.length,
+        phaseBytesCompleted: 0,
+        phaseBytesTotal: totalBytes,
     });
-    // Clean out existing data to ensure consistency on full re-index
-    deleteAllSymbols(db);
-    db.run('DELETE FROM "references";');
-    db.run("DELETE FROM dependencies;");
-    db.run("DELETE FROM mcp_tools;");
-    db.run("DELETE FROM index_state;");
+    // Clean out existing data to ensure consistency on full re-index.
+    //
+    // Skipped when resuming, which is the whole point: this wipe is why an
+    // interrupted clean index used to lose everything it had done. Resuming into
+    // a database it had just emptied would be indistinguishable from starting
+    // over.
+    if (!resume) {
+        deleteAllSymbols(db);
+        db.run('DELETE FROM "references";');
+        db.run("DELETE FROM dependencies;");
+        db.run("DELETE FROM mcp_tools;");
+        db.run("DELETE FROM index_state;");
+    }
+    // On a resume, everything already recorded and still matching disk is done.
+    // Counted toward progress rather than dropped from it, so the totals stay
+    // whole-repository and the run visibly picks up where it stopped instead of
+    // appearing to start a smaller job.
+    //
+    // Sizes come from the stored `index_state` rows, not fresh stats: the drift
+    // check just proved they still match, so re-measuring 600,000 files to learn
+    // what the database already knows would be the expensive way to be no more
+    // correct.
+    let workList = files;
+    let resumedFiles = 0;
+    let resumedBytes = 0;
+    if (resume) {
+        const pending = [];
+        for (const file of files) {
+            if (fileDriftedFromIndexState(db, repoPath, file)) {
+                pending.push(file);
+                continue;
+            }
+            resumedFiles++;
+            resumedBytes +=
+                db
+                    .query("SELECT size FROM index_state WHERE filePath = ?")
+                    .get(file)?.size ?? 0;
+        }
+        workList = pending;
+        completedBytes = resumedBytes;
+        progress?.("indexing-files", resumedFiles, `Resuming: ${resumedFiles.toLocaleString()} of ${files.length.toLocaleString()} files already indexed`, {
+            phaseTotal: files.length,
+            phaseBytesCompleted: resumedBytes,
+            phaseBytesTotal: totalBytes,
+        });
+    }
     // Process files sequentially to ensure thread-safe SQLite transactions.
     // Extraction (buildFileIndexResult, pure) still happens one file at a
     // time here; only the write is batched, via `pendingWrites`, so the
@@ -8183,14 +8388,21 @@ async function indexRepo(repoPath, db, progress, skipEmbeddings = false, publish
     };
     // Progress is reported against a single counter so the pool and the
     // sequential path can interleave without the count going backwards.
-    let processed = 0;
+    let processed = resumedFiles;
     const afterFile = async (file) => {
         if (pendingWrites.length >= INDEX_WRITE_BATCH_SIZE)
             flushPendingWrites();
-        recordIndexState(db, repoPath, file);
+        completedBytes += recordIndexState(db, repoPath, file);
         processed++;
+        // Persisted on the same cadence as the write batches rather than only at
+        // the end, so an interrupted index keeps what it learned. Cheap: one meta
+        // row per 200 files, not per file.
+        if (processed % INDEX_WRITE_BATCH_SIZE === 0)
+            persistUnparsedTally(db, unparsedByExtension);
         progress?.("indexing-files", processed, `Indexing ${files.length.toLocaleString()} files`, {
             phaseTotal: files.length,
+            phaseBytesCompleted: completedBytes,
+            phaseBytesTotal: totalBytes,
         });
         if (Date.now() - lastYieldAt >= INDEX_EVENT_LOOP_YIELD_MS) {
             await yieldToIndexEventLoop();
@@ -8215,7 +8427,7 @@ async function indexRepo(repoPath, db, progress, skipEmbeddings = false, publish
             // cannot disagree about where a file belongs.
             const eligible = [];
             const inline = [];
-            for (const file of files) {
+            for (const file of workList) {
                 if (isWorkerEligibleFile(path.join(repoPath, file), file))
                     eligible.push({ absolutePath: path.join(repoPath, file), relativePath: file, repoPath });
                 else
@@ -8246,7 +8458,7 @@ async function indexRepo(repoPath, db, progress, skipEmbeddings = false, publish
             }
         }
         else {
-            for (const file of files) {
+            for (const file of workList) {
                 await indexOneInline(file);
                 await afterFile(file);
             }
@@ -8270,7 +8482,11 @@ async function indexRepo(repoPath, db, progress, skipEmbeddings = false, publish
     setMeta(db, "knodinVersion", KNODIN_VERSION);
     setMeta(db, "lastSuccessfulReconciliation", new Date().toISOString());
     setMeta(db, "mcpBackfillVersion", "17");
-    setMeta(db, COVERAGE_UNPARSED_META_KEY, JSON.stringify(Object.fromEntries(unparsedByExtension)));
+    persistUnparsedTally(db, unparsedByExtension);
+    // Only now is the tally a measurement rather than a lower bound. Clearing the
+    // marker LAST, after the final write, means any failure above leaves it set
+    // and the tally honestly flagged incomplete.
+    setMeta(db, COVERAGE_TALLY_IN_PROGRESS_META_KEY, "");
     recordFreshnessBaseline(repoPath, db);
     if (publishProcessState)
         indexGeneration++;
@@ -11340,6 +11556,13 @@ function withStaleness(engine, claimRepository, openDb, openPolicy) {
                 row.staleness = staleness;
             return page;
         },
+        searchText(term, repoPath, options) {
+            claimRepository(repoPath);
+            // No staleness annotation: this reads the working tree directly rather
+            // than the graph, so its answers are current by construction and
+            // stamping them with the index's freshness would misreport them.
+            return engine.searchText(term, repoPath, options);
+        },
         async query(pattern, target, repoPath, to, limit, depth, detailLevel, selector, impactOptions, options) {
             claimRepository(repoPath);
             const result = await engine.query(pattern, target, repoPath, to, limit, depth, detailLevel, selector, impactOptions, options);
@@ -11654,7 +11877,18 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
             if (!db)
                 throw new Error("candidate database did not open");
             if (!changes) {
-                await indexRepo(resolved, db, options?.onProgress, options?.skipEmbeddings === true, false);
+                // Claim the build before touching anything, and record which tree it
+                // is for. A candidate carrying this marker is one a previous run left
+                // mid-build; without the commit, a resume could silently continue a
+                // build of a tree that has since moved on and promote a graph that
+                // never described any single state of the repository.
+                setMeta(db, CLEAN_INDEX_IN_PROGRESS_META_KEY, "1");
+                setMeta(db, CLEAN_INDEX_HEAD_META_KEY, gitHead(resolved) ?? "");
+                await indexRepo(resolved, db, options?.onProgress, options?.skipEmbeddings === true, false, options?.resume === true);
+                // Cleared only after indexRepo returns. Anything that fails or is
+                // killed above leaves it set, which is exactly what makes the
+                // candidate recognisable as resumable rather than abandoned.
+                setMeta(db, CLEAN_INDEX_IN_PROGRESS_META_KEY, "");
                 return { reconciled: collectRepoFiles(resolved) };
             }
             const reconciled = [...new Set(changes)]
@@ -13491,6 +13725,27 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
         },
         async index(repoPath, files, clean = false, options) {
             const resolved = path.resolve(repoPath);
+            // Expand `--under` before anything else, so everything downstream sees an
+            // ordinary explicit-file index and no path can route a scoped rebuild
+            // into the destructive full-index branch.
+            const scopedUnder = options?.under;
+            if (scopedUnder !== undefined && (!files || files.length === 0)) {
+                const prefix = path
+                    .relative(resolved, path.resolve(resolved, scopedUnder))
+                    .split(path.sep)
+                    .join("/");
+                if (prefix.startsWith("..") || path.isAbsolute(prefix))
+                    throw new Error(`knodin index --under: ${scopedUnder} is outside the repository`);
+                const collected = collectRepoFilesWithCoverage(resolved);
+                files =
+                    prefix === ""
+                        ? collected.files
+                        : collected.files.filter((file) => file === prefix || file.startsWith(`${prefix}/`));
+                // Failing loudly rather than indexing nothing and reporting success:
+                // a silent no-op here would look identical to a completed rebuild.
+                if (files.length === 0)
+                    throw new Error(`knodin index --under: no indexable files under ${scopedUnder || "the repository root"}`);
+            }
             const indexCoordination = acquireLifecycleCoordination({
                 command: "index",
                 repository: resolved,
@@ -13503,13 +13758,27 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                     !process.env.VITEST &&
                     process.env.NODE_ENV !== "test") {
                     const progress = createIndexProgressReporter(options?.onProgress);
-                    progress("starting", 0, "Creating isolated clean-index candidate");
-                    const candidate = await engine.createCandidate(resolved);
+                    // Look for a build a previous run left unfinished before starting a
+                    // new one. A candidate survives only when the process was killed —
+                    // a failure discards it — so a survivor is precisely the case worth
+                    // continuing.
+                    const resumable = findResumableCandidate(resolved);
+                    // Adopt it into the engine's registry. Ownership is what
+                    // reconcile/audit/promote check, and a candidate recovered from disk
+                    // was never registered because the process that created it is gone.
+                    if (resumable)
+                        candidates.set(resumable.id, resumable);
+                    const candidate = resumable ?? (await engine.createCandidate(resolved));
+                    if (resumable)
+                        progress("starting", 0, "Resuming the interrupted clean index (previous progress kept)");
+                    else
+                        progress("starting", 0, "Creating isolated clean-index candidate");
                     let promoted = false;
                     try {
                         const reconciliation = await engine.reconcileCandidate(candidate, resolved, undefined, {
                             onProgress: progress,
                             skipEmbeddings: options?.skipEmbeddings,
+                            resume: resumable !== null,
                         });
                         progress("verifying", 0, "Deep-auditing clean-index candidate", {
                             phaseTotal: 1,
@@ -13650,7 +13919,7 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                         catch (_) { }
                         if (!clean && hasSymbols) {
                             progress("collecting-files", 0, "Checking existing local graph for changes");
-                            await reconcileIndex(repoPath, db, progress);
+                            await reconcileIndex(repoPath, db, progress, options?.skipEmbeddings === true);
                         }
                         else {
                             await indexRepo(repoPath, db, progress, options?.skipEmbeddings === true);
@@ -13768,9 +14037,26 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                     progress("completed", completed, health.status === "healthy"
                         ? completionMessage
                         : `${completionMessage}; verification found ${issueCount.toLocaleString()} issue(s)`, { phaseTotal: completed });
+                    // A scoped rebuild leaves the stored coverage tally describing a
+                    // different run than the graph it now sits beside. Left alone it
+                    // would still be present, and therefore still reported as measured
+                    // fact — the stale-and-authoritative case. Marking it incomplete
+                    // makes `status` report a lower bound until a full index restores a
+                    // whole-repository measurement.
+                    //
+                    // Only for an explicit `--under`, not for ordinary file arguments:
+                    // the lifecycle hooks index changed files constantly, and flagging
+                    // the tally on every commit would make the signal meaningless noise.
+                    if (scopedUnder !== undefined)
+                        setMeta(db, COVERAGE_TALLY_IN_PROGRESS_META_KEY, "1");
                     return {
                         indexed,
                         unchanged,
+                        // Measured from the graph rather than inferred from the flag: a
+                        // run that deferred embeddings and a run that never had any are
+                        // the same state to a consumer, and a partially embedded graph is
+                        // neither.
+                        semanticReadiness: semanticReadinessFor(db),
                         scip: scipReport,
                         sarif: sarifReport,
                         verification: {
@@ -13795,6 +14081,15 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                 indexCoordination.release();
             }
         },
+        async searchText(term, repoPath, options = {}) {
+            if (term.length === 0)
+                throw new Error("knodin searchText: term must not be empty");
+            // Reads the working tree, not the graph, so it needs no open database
+            // and no freshness check. `getLanguageForFile` is the same grammar
+            // loader indexing uses, which is what makes the classification
+            // evidence rather than a heuristic over file extensions.
+            return searchRepoText(path.resolve(repoPath), term, getLanguageForFile, () => new Parser(), options);
+        },
         async search(query, repoPath, limit, options = {}) {
             const resolvedRepoPath = path.resolve(repoPath);
             const offset = options.offset ?? 0;