knodin 0.10.2 → 0.10.3

package/dist/bin/cli.js

@@ -138,16 +138,29 @@ function formatRepairHuman(result) {
     const detail = firstIssue ? ` First issue: ${firstIssue}.` : "";
     return `Repair finished with ${outstanding.toLocaleString()} remaining issue(s).${detail} Run \`knodin status --deep\` for details.\n`;
 }
+/**
+ * The semantic gap, stated rather than left to be discovered.
+ *
+ * An index that deferred embeddings leaves `search` returning a short list, and
+ * a short list is indistinguishable from a thorough search that found little.
+ * Saying nothing here is what turns a deliberate deferral into a silent one.
+ */
+function formatSemanticGap(readiness) {
+    if (readiness === undefined || readiness === "ready")
+        return "";
+    return ` Semantic coverage is ${readiness}: \`search\` will under-return until \`knodin index\` completes embeddings.`;
+}
 function formatIndexHuman(result) {
+    const semantic = formatSemanticGap(result.semanticReadiness);
     if (result.indexed.length === 0 && result.unchanged.length > 0) {
         const noun = result.unchanged.length === 1 ? "file" : "files";
-        return `Graph already current: ${result.unchanged.length.toLocaleString()} requested ${noun} needed no work; health verified.\n`;
+        return `Graph already current: ${result.unchanged.length.toLocaleString()} requested ${noun} needed no work; health verified.${semantic}\n`;
     }
     const unchanged = result.unchanged.length > 0
         ? `; ${result.unchanged.length.toLocaleString()} already current`
         : "";
     const noun = result.indexed.length === 1 ? "file" : "files";
-    return `Index complete: ${result.indexed.length.toLocaleString()} ${noun} indexed${unchanged}; graph health verified.\n`;
+    return `Index complete: ${result.indexed.length.toLocaleString()} ${noun} indexed${unchanged}; graph health verified.${semantic}\n`;
 }
 function formatIndexVerificationError(result) {
     const firstIssue = result.verification.missing.files[0] ?? result.verification.missing.records[0];
@@ -2168,6 +2181,8 @@ async function main() {
                 process.exit(1);
             }
             const clean = rest.includes("--clean") || rest.includes("--force");
+            const skipEmbeddings = rest.includes("--skip-embeddings");
+            const under = selectorValue("--under");
             const scipPath = selectorValue("--scip");
             const sarifPath = selectorValue("--sarif");
             // A bound the operator cannot move is just a failure, so every import
@@ -2198,6 +2213,8 @@ async function main() {
             let indexResult;
             try {
                 indexResult = await engine.index(plan.repo, plan.files, clean, {
+                    skipEmbeddings,
+                    ...(under !== undefined ? { under } : {}),
                     scip: scipPath
                         ? {
                             path: scipPath,
@@ -2904,6 +2921,17 @@ async function main() {
         process.exitCode = finalExitCode;
         return;
     }
+    // `search` has no human formatter — results fall through to the generic JSON
+    // emitter — so a semantically incomplete graph produced a short list with
+    // nothing saying why. The list looks like a thorough answer, which is the
+    // whole failure. Printed to stderr so it annotates without corrupting output
+    // anyone is piping.
+    if (cmd === "search" && !jsonOutput) {
+        const readiness = result.semanticReadiness;
+        const gap = formatSemanticGap(readiness);
+        if (gap)
+            process.stderr.write(`${gap.trim()}\n`);
+    }
     if (cmd === "status" && !jsonOutput) {
         process.stdout.write(formatStatusHuman(boundedResult));
         process.exitCode = finalExitCode;

package/dist/src/cli-args.js

@@ -36,6 +36,10 @@ const GLOBAL_BOOLEAN_FLAGS = new Set(["--exclude-tests", "--data-flow", "--json"
  * not to index the log as a source file.
  */
 const COMMAND_VALUE_FLAGS = new Set([
+    // Takes a directory. Without this its argument reads as a positional, and
+    // `knodin index --under src` would be rejected as "a directory positional"
+    // by the very rule that exists to stop people scoping this way by accident.
+    "--under",
     "--scip",
     "--scip-max-bytes",
     "--scip-max-files",

package/dist/src/cli-model.js

@@ -288,6 +288,8 @@ function createCliProgram(capture = () => { }) {
     leaf(program, "index [files...]", "index a repository or selected files", capture)
         .option("--clean", "rebuild selected index state")
         .option("--force", "force clean indexing")
+        .option("--skip-embeddings", "build structure only and defer semantic embeddings; `search` under-returns until a later `knodin index` completes them")
+        .option("--under <dir>", "rebuild only the files under a repository-relative directory; coverage is then reported as a lower bound until a full index runs")
         .option("--scip <file>", "opt in to a bounded local SCIP protobuf import")
         .addOption(option("--scip-max-bytes <count>", "raise the SCIP input size ceiling", "integer"))
         .addOption(option("--scip-max-files <count>", "raise the SCIP document ceiling", "integer"))

package/dist/src/engine/candidate-database.js

@@ -66,6 +66,59 @@ export function candidateRoot(repo) {
 export function promotionMarkerPath(repo) {
     return path.join(resolveStateDir(repo), PROMOTION_MARKER);
 }
+/**
+ * Candidates left on disk for this repository, newest first.
+ *
+ * A clean index discards its candidate on failure, but a killed process runs no
+ * discard — so survivors are exactly the runs that were interrupted rather than
+ * the ones that failed. Listing them is what lets the next run continue instead
+ * of repeating hours of work.
+ *
+ * Returns descriptors only. Whether any of them is safe to resume is decided by
+ * the caller from the database's own contents, not from the fact it exists.
+ */
+export function listCandidates(repo) {
+    const resolvedRepo = path.resolve(repo);
+    const root = candidateRoot(resolvedRepo);
+    let entries;
+    try {
+        entries = fs.readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory() || !entry.name.startsWith("candidate-"))
+            continue;
+        const databasePath = path.join(root, entry.name, "db.sqlite");
+        let modifiedMs;
+        try {
+            modifiedMs = fs.statSync(databasePath).mtimeMs;
+        }
+        catch {
+            // A directory with no database is a half-created candidate, not a
+            // resumable one.
+            continue;
+        }
+        found.push({
+            candidate: {
+                schemaVersion: 1,
+                id: entry.name,
+                repo: resolvedRepo,
+                databasePath,
+                createdAt: new Date(modifiedMs).toISOString(),
+            },
+            modifiedMs,
+        });
+    }
+    // Sorted as its own statement rather than mid-chain: an in-place `sort`
+    // inside an expression mutates the array being read, which is harmless for
+    // this local but reads as a side effect at a glance. (`toSorted` would be
+    // the nicer form but needs a newer `lib` than this project targets.)
+    found.sort((a, b) => b.modifiedMs - a.modifiedMs);
+    return found.map((item) => item.candidate);
+}
 export function allocateCandidate(repo) {
     const resolvedRepo = path.resolve(repo);
     const root = candidateRoot(resolvedRepo);

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";
@@ -373,6 +373,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 +7089,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 +7260,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 +7395,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 +7406,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 +7663,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 +7757,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 +7876,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 +8273,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 +8291,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 +8387,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 +8426,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 +8457,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 +8481,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++;
@@ -11654,7 +11869,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 +13717,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 +13750,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 +13911,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 +14029,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: {

package/dist/src/init-progress.js

@@ -20,7 +20,7 @@ function formatDuration(seconds) {
         return `${Math.ceil(seconds)}s`;
     return `${Math.floor(seconds / 60)}m ${Math.ceil(seconds % 60)}s`;
 }
-export function formatProgress(event, ratePerSecond, operation = "init") {
+export function formatProgress(event, ratePerSecond, operation = "init", bytesPerSecond) {
     const model = event.modelFile ? ` (${event.modelFile})` : "";
     const total = event.phaseTotal;
     if (total === undefined)
@@ -29,13 +29,34 @@ export function formatProgress(event, ratePerSecond, operation = "init") {
         ? `${formatBytes(event.phaseCompleted)} / ${formatBytes(total)}`
         : `${formatCount(event.phaseCompleted)} / ${formatCount(total)}`;
     const percent = total > 0 ? ` (${Math.floor((event.phaseCompleted / total) * 100)}%)` : "";
-    const eta = ratePerSecond && total > event.phaseCompleted
-        ? ` • ~${formatDuration((total - event.phaseCompleted) / ratePerSecond)} remaining`
+    // Both counters, because they answer different questions and on a real
+    // repository they disagree. Measured on a 902,960-file Salesforce checkout:
+    // 435 files over 1 MB hold 78% of the bytes, so "71% of files" was about a
+    // quarter of the work. Showing only files is what made a working index look
+    // wedged for twenty minutes.
+    const bytesTotal = event.phaseBytesTotal;
+    const bytesDone = event.phaseBytesCompleted;
+    const bytes = bytesTotal !== undefined && bytesDone !== undefined && bytesTotal > 0
+        ? ` • ${formatBytes(bytesDone)} / ${formatBytes(bytesTotal)} (${Math.floor((bytesDone / bytesTotal) * 100)}%)`
         : "";
+    // Prefer the byte rate: it tracks the shape of the work rather than the
+    // length of the list. Falls back to the item rate when the phase carries no
+    // byte size, which keeps model download and embedding phases as they were.
+    const byteEta = bytesPerSecond && bytesTotal !== undefined && bytesDone !== undefined && bytesTotal > bytesDone
+        ? (bytesTotal - bytesDone) / bytesPerSecond
+        : undefined;
+    const itemEta = ratePerSecond && total > event.phaseCompleted
+        ? (total - event.phaseCompleted) / ratePerSecond
+        : undefined;
+    const remaining = byteEta ?? itemEta;
+    // Labelled an estimate because it is one, and because a confidently wrong
+    // number is worse than an obviously approximate one — this workload spans
+    // three orders of magnitude in cost per file.
+    const eta = remaining === undefined ? "" : ` • ~${formatDuration(remaining)} remaining (est.)`;
     const rate = ratePerSecond && event.phase !== "embedding-model"
         ? ` • ${ratePerSecond.toFixed(ratePerSecond >= 10 ? 0 : 1)}/s`
         : "";
-    return `[${operation}:${event.phase}] ${counter}${percent} ${event.message}${model}${rate}${eta}`;
+    return `[${operation}:${event.phase}] ${counter}${percent}${bytes} ${event.message}${model}${rate}${eta}`;
 }
 /**
  * Human-only init feedback. It writes to stderr, leaving stdout stable for the
@@ -61,6 +82,7 @@ export function createInitProgressRenderer(options) {
     let lastPercentBucket = -1;
     let phaseStartedElapsedMs = 0;
     let phaseStartedCompleted = 0;
+    let phaseStartedBytes = 0;
     const scheduleHeartbeat = () => {
         if (heartbeat !== undefined || stopped)
             return;
@@ -126,17 +148,26 @@ export function createInitProgressRenderer(options) {
             if (phaseChanged) {
                 phaseStartedElapsedMs = event.elapsedMs;
                 phaseStartedCompleted = event.phaseCompleted;
+                phaseStartedBytes = event.phaseBytesCompleted ?? 0;
             }
             const phaseElapsedSeconds = Math.max(0, event.elapsedMs - phaseStartedElapsedMs) / 1_000;
             const ratePerSecond = phaseElapsedSeconds > 0 && event.phaseCompleted > phaseStartedCompleted
                 ? (event.phaseCompleted - phaseStartedCompleted) / phaseElapsedSeconds
                 : undefined;
+            // Measured from the start of the phase, not from process start, so the
+            // cold-start window (wasm init, grammar load, embedder setup) does not
+            // drag the estimate. Extrapolating from that window overstated a real
+            // run by roughly ten times.
+            const bytesDone = event.phaseBytesCompleted;
+            const bytesPerSecond = phaseElapsedSeconds > 0 && bytesDone !== undefined && bytesDone > phaseStartedBytes
+                ? (bytesDone - phaseStartedBytes) / phaseElapsedSeconds
+                : undefined;
             const completed = event.phaseTotal !== undefined && event.phaseCompleted >= event.phaseTotal;
             if (tty && !phaseChanged && !completed && now() - lastWriteAt < TTY_THROTTLE_MS)
                 return;
             if (!tty && !phaseChanged && bucket <= lastPercentBucket && !completed)
                 return;
-            write(formatProgress(event, ratePerSecond, operation));
+            write(formatProgress(event, ratePerSecond, operation, bytesPerSecond));
             lastPhase = event.phase;
             lastPercentBucket = Math.max(lastPercentBucket, bucket);
         },

package/dist/src/release-compatibility.js

@@ -0,0 +1,95 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parseVersion } from "./update-policy.js";
+/**
+ * Classify a version transition.
+ *
+ * Returns `null` when the transition is not a forward release — equal versions,
+ * a downgrade, or an unparseable input — so callers distinguish "cannot say"
+ * from a confident answer. Returning a default here would put a guess into
+ * published metadata, which is the failure this whole change removes.
+ *
+ * ## The 0.x rule, stated rather than inherited
+ *
+ * Pre-1.0, the MINOR is the breaking axis: `0.10.x` to `0.11.0` breaks, while
+ * `0.10.1` to `0.10.2` does not. This is conventional SemVer for major-zero and
+ * it is also what this project's own history shows — `0.9.0` and `0.10.0` were
+ * genuinely breaking and were labelled so, while `0.10.1` and `0.10.2` were
+ * bugfix releases published under the same label because the field was a
+ * constant.
+ *
+ * `policyAllows` in update-policy.ts deliberately does NOT encode this: it
+ * treats major-zero like any other major, which is correct for deciding whether
+ * an automatic update is safe but would classify every 0.x release as
+ * non-breaking here. Reusing it would be the obvious mistake.
+ */
+export function classifyCompatibility(previous, next) {
+    const from = parseVersion(previous);
+    const to = parseVersion(next);
+    if (!from || !to)
+        return null;
+    const [fromMajor, fromMinor, fromPatch] = from.core;
+    const [toMajor, toMinor, toPatch] = to.core;
+    // Not a forward release. A caller asking about a downgrade or a no-op has a
+    // different problem than a mislabelled release.
+    if (toMajor < fromMajor)
+        return null;
+    if (toMajor === fromMajor && toMinor < fromMinor)
+        return null;
+    if (toMajor === fromMajor && toMinor === fromMinor && toPatch <= fromPatch)
+        return null;
+    if (toMajor !== fromMajor)
+        return "breaking";
+    // Major-zero: the minor carries what the major carries after 1.0.
+    if (toMajor === 0)
+        return toMinor !== fromMinor ? "breaking" : "compatible";
+    return toMinor !== fromMinor ? "compatible-with-additions" : "compatible";
+}
+/**
+ * The version of the release immediately before `version`, taken from the
+ * release-notes directory.
+ *
+ * Derived from `docs/releases/` rather than git tags on purpose: the repository
+ * has no previous-tag lookup anywhere, this needs no subprocess, and the notes
+ * are already required to exist for the release being cut — `docs-integrity`
+ * asserts the current version's file is present and packaged. Using a source
+ * that is already load-bearing means this cannot silently disagree with what
+ * ships.
+ *
+ * Returns `null` when there is no earlier release, which is a real state for the
+ * first one.
+ */
+export function previousReleaseVersion(releasesDir, version) {
+    let entries;
+    try {
+        entries = fs.readdirSync(releasesDir);
+    }
+    catch {
+        return null;
+    }
+    const target = parseVersion(version);
+    if (!target)
+        return null;
+    let best = null;
+    for (const entry of entries) {
+        if (path.extname(entry) !== ".md")
+            continue;
+        const candidateText = path.basename(entry, ".md");
+        const candidate = parseVersion(candidateText);
+        if (!candidate)
+            continue;
+        if (compareCore(candidate.core, target.core) >= 0)
+            continue;
+        if (!best || compareCore(candidate.core, best.core) > 0)
+            best = { text: candidateText, core: candidate.core };
+    }
+    return best?.text ?? null;
+}
+function compareCore(left, right) {
+    for (let index = 0; index < 3; index++) {
+        const difference = (left[index] ?? 0) - (right[index] ?? 0);
+        if (difference !== 0)
+            return difference;
+    }
+    return 0;
+}

package/dist/src/release-preflight.js

@@ -3,6 +3,7 @@ import { createHash, createPublicKey } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { compareBytes } from "./compare.js";
+import { classifyCompatibility, previousReleaseVersion } from "./release-compatibility.js";
 import { validateRootCeremonyManifest } from "./update-ceremony.js";
 import { canonicalizeUpdateMetadata, verifyUpdateRootChain, } from "./update-trust.js";
 export const RELEASE_PREFLIGHT_REPOSITORY_COMMANDS = [
@@ -486,6 +487,23 @@ export function evaluateReleasePreflight(options) {
     const packageManifest = record(parseJson(packageFile.bytes, "package manifest"), "package manifest");
     if (packageManifest.version !== plan.version)
         fail("package version does not equal release-plan version");
+    // `knodin.compatibility` ships in the tarball and is read out of it by the
+    // Homebrew tap. Nothing inside this repository consumes it, so a wrong value
+    // reaches consumers without anything failing — it was a hardcoded "breaking"
+    // across four releases, two of which were bugfix patches. This is the last
+    // gate that sees the manifest before it is published.
+    const declaredCompatibility = record(packageManifest.knodin ?? {}, "package manifest knodin block").compatibility;
+    const previousRelease = previousReleaseVersion(path.join(repositoryRoot, "docs", "releases"), plan.version);
+    if (previousRelease !== null) {
+        const derived = classifyCompatibility(previousRelease, plan.version);
+        // A null derivation means the version did not move forward, which the
+        // version check above should already have caught; failing here rather than
+        // skipping keeps an unexplained state from passing silently.
+        if (derived === null)
+            fail(`cannot classify compatibility from ${previousRelease} to ${plan.version}`);
+        else if (declaredCompatibility !== derived)
+            fail(`package knodin.compatibility is ${JSON.stringify(declaredCompatibility)} but ${previousRelease} to ${plan.version} is ${derived}`);
+    }
     const workflowFile = readBoundedRegularFile(repositoryRoot, path.join(repositoryRoot, plan.workflow.path), "C64 candidate workflow", MAX_MANIFEST_BYTES);
     if (!git.isTracked(workflowFile.relativePath))
         fail("C64 candidate workflow must be checked in");

package/dist/src/update-policy.js

@@ -234,7 +234,12 @@ function baseResult(options, status) {
         networkUsed: false,
     };
 }
-function parseVersion(version) {
+/**
+ * Exported so release classification can reuse this parser rather than adding a
+ * third hand-rolled copy (`src/manager-update.ts:424` is the second, and a
+ * de-duplication candidate). Strict SemVer: leading zeros are rejected.
+ */
+export function parseVersion(version) {
     const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(version);
     if (!match)
         return null;

package/docs/releases/0.10.3.md

@@ -0,0 +1,93 @@
+# knodin 0.10.3
+
+Four changes, all from one observation: after 0.10.2 fixed a parser leak that had
+left 174,205 files silently unparsed on a large repository, the recovery advice
+turned out to be unusable. A full reindex of that checkout has no knowable cost,
+no way to ask for less work, and no way to survive an interruption.
+
+## Indexing reports how much work is left, not just how many files
+
+A full index of a 902,960-file Salesforce checkout appeared to hang for twenty
+minutes at 71%. It had not hung — it had reached the profiles.
+
+Progress was counted in files while the cost lives in bytes, and on that
+repository the two disagree violently: **435 files over 1 MB hold 78% of all
+source bytes.** So the counter raced through the cheap files and appeared to
+stall exactly when the expensive ones began, which is the moment an operator is
+most likely to conclude the process is wedged and kill it. The only way to tell
+grinding from hung was to read the process's accumulated CPU time.
+
+Both counters are now reported, and the estimate is derived from the byte rate.
+Files answer "how far through the list"; bytes answer "how much work is left".
+
+The estimate is labelled an estimate. During that one run, three separate
+completion figures were derived from observed rates — 38 hours, 4 hours, and 15
+minutes — and every one was wrong, because the rate ranged from 6.5 to 361 files
+per second before collapsing to 0.065. Rates are now measured from the start of
+the phase rather than process start, so the cold-start window no longer drags the
+estimate; extrapolating from it is what produced the 38-hour figure.
+
+## Rebuild one subtree with `--under`
+
+`knodin index --under <dir>` rebuilds only that directory. Previously the
+intuitive attempt was also the worst one: a lone directory argument means "index
+this whole repository".
+
+The file set is resolved inside the engine rather than by expanding paths
+yourself, so a scoped rebuild indexes exactly the files a full index would. A
+scope that matches nothing fails rather than reporting a successful rebuild of
+nothing.
+
+Coverage is reported as a lower bound afterwards, because a whole-repository
+tally no longer describes a partially rebuilt graph. Trading a graph you were
+told to distrust for one that is silently partial would be worse than doing
+nothing.
+
+## Defer embeddings with `--skip-embeddings`
+
+The embedding phase dominates indexing cost, and the engine has always supported
+deferring it — only mirrors could ask. `knodin index --skip-embeddings` now
+builds structure alone, leaving `explain`, `query` and impact answerable while
+semantic search waits.
+
+The gap is stated rather than left to be discovered. An index that defers
+embeddings says so, and `knodin search` now announces that it will under-return
+until they are built. A short result list is otherwise indistinguishable from a
+thorough search that found little.
+
+Running `knodin index` again completes the deferred pass, and only the symbols
+still lacking embeddings are processed.
+
+## An interrupted `--clean` resumes
+
+A clean index builds into a candidate database and promotes it atomically. That
+is deliberate — it is why a failed rebuild cannot leave a half-built graph in
+place of a working one, and it is unchanged.
+
+But a killed process runs no discard, so the candidate survived on disk and the
+next run ignored it and started over. On a repository where the rebuild takes
+hours, an interruption cost all of it.
+
+The next `knodin index --clean` now continues that build, skipping files already
+recorded whose contents still match disk, and says how many it kept. Resumption
+is refused when the tree has moved on since — continuing there would promote a
+graph that never described any single state of the repository — and refused for
+a candidate that was never marked as an interrupted build. Both cases fall back
+to a full rebuild rather than guessing.
+
+## Release compatibility is derived, not declared
+
+`knodin.compatibility` had been the literal string `"breaking"` since it was
+introduced, across four releases. Two of those genuinely were breaking and two
+were bugfix patches, so it was accidentally correct half the time — which is
+worse than being consistently wrong, because the correct entries make the field
+look maintained.
+
+It is now derived from the version change, with the pre-1.0 rule stated
+explicitly: below 1.0 the minor is the breaking axis, so `0.10.x` to `0.11.0`
+breaks and `0.10.2` to `0.10.3` does not. Nothing inside this repository reads
+the field — the Homebrew tap reads it from the published package — so two guards
+now check it, because otherwise nothing would.
+
+Releases already published keep the label they shipped with. Published metadata
+is immutable by design.

package/package.json

@@ -1,8 +1,8 @@
 {
 	"name": "knodin",
-	"version": "0.10.2",
+	"version": "0.10.3",
 	"knodin": {
-		"compatibility": "breaking"
+		"compatibility": "compatible"
 	},
 	"description": "knodin — source-evidenced local code intelligence with known bounds. Stable identity, fresh evidence, truthful budgets, and recoverable bounded views.",
 	"license": "MIT",
@@ -74,6 +74,7 @@
 		"docs/releases/0.10.0.md",
 		"docs/releases/0.10.1.md",
 		"docs/releases/0.10.2.md",
+		"docs/releases/0.10.3.md",
 		"docs/assets/knodin-favicon.svg",
 		"docs/SYSTEMS-AND-RELATIONSHIPS.md",
 		"docs/TELEMETRY.md",