akm-cli 0.9.14 → 0.9.15-beta.1

package/dist/indexer/indexer.js

@@ -8,7 +8,7 @@ import { adapterForId } from "../core/adapter/registry.js";
 import { isHttpUrl, toErrorMessage } from "../core/common.js";
 import { concurrentMap } from "../core/concurrent.js";
 import { ConfigError } from "../core/errors.js";
-import { isLoopbackEndpoint } from "../core/loopback.js";
+import { defaultConcurrencyForEndpoint } from "../core/loopback.js";
 import { classifyPathAccess, describeInaccessiblePath } from "../core/path-access.js";
 import { getDbPath } from "../core/paths.js";
 import { SCRIPT_EXTENSIONS } from "../core/recognition-util.js";
@@ -54,20 +54,17 @@ function throwIfAborted(signal) {
 export function getDefaultLlmConcurrency(llmConfig) {
     if (typeof llmConfig?.concurrency === "number")
         return llmConfig.concurrency;
-    // Local model servers stay at 1 (single loaded model; parallel requests
-    // trigger reload thrash); an absent or unparseable endpoint fails safe as
-    // local. ONE classifier decides what "local" means (`core/loopback.ts`,
-    // shared with the workflow engine's frozen concurrency default).
-    if (isLoopbackEndpoint(llmConfig?.endpoint))
-        return 1;
-    // Remote endpoints default to a modest 2-wide pool (owner ruling 2026-07-21):
-    // enough to overlap request latency without hammering rate-limited APIs.
-    // The explicit-override branch above only fires for
-    // callers that put `concurrency` on the connection themselves —
-    // `engines.<name>.concurrency` is a valid schema field but `resolveLlmEngineUse`
-    // does NOT copy it into the resolved connection, so on the enrichment path the
-    // auto-derived 1/2 is what runs (see docs/architecture/internals/indexing.md).
-    return 2;
+    // ONE classifier decides the local-vs-remote default (`core/loopback.ts`'s
+    // `defaultConcurrencyForEndpoint`), shared with the embedding pool
+    // (`resolveEmbeddingConcurrency`, `src/llm/embedders/remote.ts`) and the
+    // workflow engine's frozen concurrency default.
+    //
+    // The explicit-override branch above only fires for callers that put
+    // `concurrency` on the connection themselves — `engines.<name>.concurrency`
+    // is a valid schema field but `resolveLlmEngineUse` does NOT copy it into
+    // the resolved connection, so on the enrichment path the auto-derived 1/2
+    // is what runs (see docs/architecture/internals/indexing.md).
+    return defaultConcurrencyForEndpoint(llmConfig?.endpoint);
 }
 function sourceOwners(sources) {
     const installations = deriveInstallations([...sources]);
@@ -192,14 +189,16 @@ async function runWalkPhase(ctx) {
  * entries. Writes `ctx.embeddingResult` for the finalize phase.
  */
 async function runEmbeddingPhase(ctx) {
-    const { db, config, signal, onProgress } = ctx;
+    const { db, config, signal, onProgress, reembed } = ctx;
     throwIfAborted(signal);
     // Forward the signal. Without it generateEmbeddingsForDb's abort machinery was
     // inert — its throwIfAborted checks and the signal it threads into embedBatch
     // (which RemoteEmbedder passes to every fetch and LocalEmbedder honours between
     // chunks) never saw a controller. Ctrl-C and the improve budget abort could not
     // stop the embedding phase, the longest phase of an index run.
-    ctx.embeddingResult = await generateEmbeddingsForDb(db, config, onProgress, signal);
+    ctx.embeddingResult = await generateEmbeddingsForDb(db, config, onProgress, signal, undefined, {
+        forceReembed: reembed,
+    });
     ctx.timing.tEmbedEnd = Date.now();
 }
 /**
@@ -489,6 +488,7 @@ async function akmIndexReal(options) {
         const full = options?.full === true;
         const clean = options?.clean === true;
         const dryRun = options?.dryRun === true;
+        const reembed = options?.reembed === true;
         // Load config and resolve all stash sources
         const { loadConfig, mutateConfig } = await import("../core/config/config.js");
         let config = loadConfig();
@@ -548,6 +548,7 @@ async function akmIndexReal(options) {
                 sourceDirs: allSourceDirs,
                 full,
                 clean,
+                reembed,
                 stashDir,
                 onProgress,
                 signal,

package/dist/indexer/materialize-embeddings.js

@@ -6,9 +6,10 @@ import { embedBatch } from "../llm/embedder.js";
 import { DETERMINISTIC_EMBED_MODEL_ID, isDeterministicEmbedEnabled } from "../llm/embedders/deterministic.js";
 import { DEFAULT_LOCAL_MODEL } from "../llm/embedders/local.js";
 import { buildTokenBoundedBatches, DEFAULT_REMOTE_BATCH_SIZE, DEFAULT_TOKEN_BUDGET, estimateTokenCount, hasRemoteEndpoint, } from "../llm/embedders/remote.js";
+import { cosineSimilarity } from "../llm/embedders/types.js";
 import { getEmbeddableEntryCount } from "../storage/repositories/index-entries-repository.js";
 import { deleteMeta, getMeta, setMeta } from "../storage/repositories/index-meta-repository.js";
-import { getAllEntriesForEmbedding, getEmbeddingCount, isVecFastPathComplete, isVecFastPathReady, purgeEmbeddings, setVecFastPathReady, upsertEmbedding, } from "../storage/repositories/index-vec-repository.js";
+import { getAllEntriesForEmbedding, getEmbeddingCount, isVecFastPathComplete, isVecFastPathReady, purgeEmbeddings, sampleEmbeddedEntriesForCanary, setVecFastPathReady, upsertEmbedding, } from "../storage/repositories/index-vec-repository.js";
 /** Identifies the embedding provider+model+dimension a stored vector was generated with. */
 export function deriveSemanticProviderFingerprint(embedding) {
     if (isDeterministicEmbedEnabled()) {
@@ -22,12 +23,159 @@ export function deriveSemanticProviderFingerprint(embedding) {
     }
     return `local:${embedding?.localModel ?? DEFAULT_LOCAL_MODEL}`;
 }
+/** How often (in stored entries) to emit a progress line during a large embedding run (#954). */
+const PROGRESS_INTERVAL = 500;
+/**
+ * Number of already-embedded entries sampled for the fingerprint-rename
+ * canary (#955) — small and cheap even against a slow local server; a
+ * handful of chunks is a strong compatibility signal (a different model
+ * cannot plausibly land near-identical vectors by chance).
+ */
+const CANARY_SAMPLE_SIZE = 8;
+/**
+ * Minimum median cosine similarity between stored and freshly re-embedded
+ * canary vectors for a fingerprint-string change to be treated as a
+ * same-model rename rather than a real model change (#955).
+ */
+const CANARY_SIMILARITY_THRESHOLD = 0.999;
+/**
+ * Pure decision: do stored vectors remain valid against freshly re-embedded
+ * canary samples? The ONE place that computes the canary's similarity
+ * numbers — callers must use this result rather than recomputing it (#955).
+ *
+ * An empty sample means nothing is stored to lose or verify against, so
+ * there is nothing to decide — keep.
+ *
+ * A sample whose re-embed FAILED (`fresh === undefined`, e.g. a provider
+ * sub-batch that was skipped) is EXCLUDED from the similarity computation
+ * entirely, not scored as zero: a partial provider failure is not evidence
+ * of a different model (#955). A dimension mismatch on a successful
+ * re-embed still counts as zero similarity via {@link cosineSimilarity}'s
+ * own dimension-mismatch guard — that IS evidence. When half or fewer of
+ * the sampled entries re-embedded successfully, the sample is too thin to
+ * trust either verdict — the outcome is `unverifiable`, the same outcome a
+ * total canary failure already produces.
+ *
+ * Otherwise the MEDIAN pairwise cosine similarity of the verified samples
+ * must clear {@link CANARY_SIMILARITY_THRESHOLD}; the median (not the
+ * minimum or mean) tolerates one stale or lightly-edited sample without
+ * either discarding a real match or being fooled by it.
+ */
+export function decideEmbeddingCompatibility(pairs) {
+    if (pairs.length === 0)
+        return { outcome: "keep", medianSimilarity: undefined, verifiedSamples: 0 };
+    const verified = pairs.filter((pair) => pair.fresh !== undefined);
+    if (verified.length * 2 <= pairs.length) {
+        return { outcome: "unverifiable", medianSimilarity: undefined, verifiedSamples: verified.length };
+    }
+    const similarities = verified.map((pair) => cosineSimilarity(pair.stored, pair.fresh));
+    const medianSimilarity = medianOf(similarities);
+    return {
+        outcome: medianSimilarity >= CANARY_SIMILARITY_THRESHOLD ? "keep" : "rebuild",
+        medianSimilarity,
+        verifiedSamples: verified.length,
+    };
+}
+function medianOf(values) {
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 0
+        ? (sorted[mid - 1] + sorted[mid]) / 2
+        : sorted[mid];
+}
+/**
+ * Identity of the embedding vectors actually observed on a run — as opposed
+ * to {@link deriveSemanticProviderFingerprint}'s CONFIG-derived string. Keys
+ * on what the server (or local model) actually reported plus the observed
+ * vector width, so a gateway/transport change that keeps returning the same
+ * underlying model can be told apart from a genuine model change without
+ * relying on the operator's config string (#955 field-review addendum).
+ * Returns undefined when nothing was actually observed this call (no vector
+ * to measure yet).
+ */
+function deriveObservedEmbeddingIdentity(embedding, observedModel, observedVectorLen) {
+    if (isDeterministicEmbedEnabled()) {
+        return `deterministic:${DETERMINISTIC_EMBED_MODEL_ID}`;
+    }
+    if (observedVectorLen === undefined)
+        return undefined;
+    if (embedding?.endpoint) {
+        return `remote:${observedModel ?? embedding.model ?? "unknown"}|${observedVectorLen}`;
+    }
+    return `local:${embedding?.localModel ?? DEFAULT_LOCAL_MODEL}|${observedVectorLen}`;
+}
+/**
+ * Run the fingerprint-rename canary: re-embed a small sample of already-
+ * stored entries with the CURRENT config and decide whether the stored
+ * index survives. Goes through the standard {@link embedBatch} facade (not a
+ * direct `RemoteEmbedder`) so every embedder branch — remote, local,
+ * deterministic, and test overrides via `_setEmbedderForTests` — is
+ * exercised identically to the main embedding pass.
+ */
+async function runEmbeddingCanary(db, config, signal) {
+    const samples = sampleEmbeddedEntriesForCanary(db, CANARY_SAMPLE_SIZE);
+    if (samples.length === 0) {
+        return { outcome: "keep", verified: false, viaIdentityMatch: false };
+    }
+    let observedModel;
+    const skips = [];
+    let canaryVectors;
+    try {
+        canaryVectors = await embedBatch(samples.map((sample) => sample.searchText), config.embedding, signal, (skip) => skips.push(skip), (_indices, _embeddings, model) => {
+            if (model)
+                observedModel = model;
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            outcome: "unverifiable",
+            message: `could not verify embedding compatibility (${message}); keeping existing vectors — rerun akm index when the endpoint is reachable`,
+        };
+    }
+    const observedVectorLen = canaryVectors.find((vector) => vector !== undefined)?.length;
+    const observedIdentity = deriveObservedEmbeddingIdentity(config.embedding, observedModel, observedVectorLen);
+    const storedIdentity = getMeta(db, "embeddingIdentity");
+    if (storedIdentity && observedIdentity && storedIdentity === observedIdentity) {
+        // The server reports the same model identity as last time — no need to
+        // even look at the cosines; the config string alone was misleading.
+        return { outcome: "keep", verified: true, identity: observedIdentity, viaIdentityMatch: true };
+    }
+    const pairs = samples.map((sample, i) => ({ stored: sample.vector, fresh: canaryVectors[i] }));
+    const decision = decideEmbeddingCompatibility(pairs);
+    if (decision.outcome === "unverifiable") {
+        // Covers both a total provider failure (RemoteEmbedder skips a failing
+        // request rather than throwing, #874, so an unreachable endpoint
+        // surfaces here as an all-`undefined` canary result, not a caught
+        // exception) and a partial one thin enough that neither verdict can be
+        // trusted (#955) — same message path either way.
+        const message = skips[0]?.message ?? "embedding provider returned no vectors for the canary sample";
+        return {
+            outcome: "unverifiable",
+            message: `could not verify embedding compatibility (${message}); keeping existing vectors — rerun akm index when the endpoint is reachable`,
+        };
+    }
+    if (decision.outcome === "keep") {
+        return {
+            outcome: "keep",
+            verified: true,
+            identity: observedIdentity,
+            viaIdentityMatch: false,
+            medianSimilarity: decision.medianSimilarity,
+        };
+    }
+    return {
+        outcome: "rebuild",
+        identity: observedIdentity,
+        reason: `vectors differ (median similarity ${decision.medianSimilarity?.toFixed(3)})`,
+    };
+}
 function throwIfAborted(signal) {
     if (signal?.aborted) {
         throw signal.reason instanceof Error ? signal.reason : new Error("index interrupted");
     }
 }
-export async function generateEmbeddingsForDb(db, config, onProgress, signal, entryIds) {
+export async function generateEmbeddingsForDb(db, config, onProgress, signal, entryIds, opts) {
     throwIfAborted(signal);
     if (config.semanticSearchMode === "off") {
         onProgress({ phase: "embeddings", message: "Semantic search disabled; skipping embeddings." });
@@ -41,12 +189,69 @@ export async function generateEmbeddingsForDb(db, config, onProgress, signal, en
     const currentFingerprint = deriveSemanticProviderFingerprint(config.embedding);
     const storedFingerprint = getMeta(db, "embeddingFingerprint");
     let targetEntryIds = entryIds;
-    if (storedFingerprint && storedFingerprint !== currentFingerprint) {
-        purgeEmbeddings(db, { dropVecTable: true });
-        deleteMeta(db, "embeddingDim");
-        // A provider/model change invalidates the entire vector generation, even
-        // when a targeted write happened to discover it first.
+    /** Set only on an actual rebuild, so the up-front "Re-embedding N entries" line names why. */
+    let rebuildReason;
+    if (opts?.forceReembed) {
+        // `akm index --reembed`: an explicit operator override, skips the canary
+        // entirely. The new fingerprint (and identity, now stale/unknown until
+        // the next successful pass observes it) is written in the SAME
+        // transaction as the purge, before any embedding request — a restart
+        // then sees a matching fingerprint and only heals what is still missing
+        // instead of purging again from zero (#955/#956).
+        db.transaction(() => {
+            purgeEmbeddings(db, { dropVecTable: true });
+            deleteMeta(db, "embeddingDim");
+            setMeta(db, "embeddingFingerprint", currentFingerprint);
+            deleteMeta(db, "embeddingIdentity");
+        })();
         targetEntryIds = undefined;
+        rebuildReason = "forced by --reembed";
+    }
+    else if (storedFingerprint && storedFingerprint !== currentFingerprint) {
+        const decision = await runEmbeddingCanary(db, config, signal);
+        if (decision.outcome === "unverifiable") {
+            // Destroying a good index because the server happens to be down right
+            // now is worse than leaving a rename unverified until the next run —
+            // keep the vectors AND the old fingerprint so the next `akm index`
+            // retries the canary instead of silently treating this as resolved.
+            warn(`[embed] ${decision.message}`);
+            onProgress({ phase: "embeddings", message: decision.message });
+            return { success: false, message: decision.message };
+        }
+        if (decision.outcome === "rebuild") {
+            db.transaction(() => {
+                purgeEmbeddings(db, { dropVecTable: true });
+                deleteMeta(db, "embeddingDim");
+                setMeta(db, "embeddingFingerprint", currentFingerprint);
+                if (decision.identity)
+                    setMeta(db, "embeddingIdentity", decision.identity);
+                else
+                    deleteMeta(db, "embeddingIdentity");
+            })();
+            targetEntryIds = undefined;
+            rebuildReason = decision.reason;
+        }
+        else {
+            // Keep: adopt the new fingerprint (and identity, when observed)
+            // immediately rather than deferring to end-of-run — nothing was
+            // purged, so there is nothing an interruption could lose, and an
+            // immediate write means a crash right after this decision does not
+            // re-run the canary needlessly on the next attempt.
+            setMeta(db, "embeddingFingerprint", currentFingerprint);
+            if (decision.identity)
+                setMeta(db, "embeddingIdentity", decision.identity);
+            if (decision.verified) {
+                const keptCount = getEmbeddingCount(db);
+                const detail = decision.viaIdentityMatch
+                    ? "server-reported model unchanged"
+                    : `stored vectors are compatible (median similarity ${decision.medianSimilarity?.toFixed(3)})`;
+                const message = `[embed] embedding model renamed (${storedFingerprint} → ${currentFingerprint}); ${detail}, keeping ${keptCount} embedding${keptCount === 1 ? "" : "s"}.`;
+                warn(message);
+                onProgress({ phase: "embeddings", message });
+            }
+            // Empty-sample case (decision.verified === false): nothing stored to
+            // lose or verify against — adopt the label silently, no purge line.
+        }
     }
     try {
         throwIfAborted(signal);
@@ -56,6 +261,11 @@ export async function generateEmbeddingsForDb(db, config, onProgress, signal, en
             setMeta(db, "embeddingFingerprint", currentFingerprint);
             return { success: true };
         }
+        if (rebuildReason) {
+            const message = `[embed] Re-embedding ${allEntries.length} entr${allEntries.length === 1 ? "y" : "ies"} because ${rebuildReason}`;
+            warn(message);
+            onProgress({ phase: "embeddings", message });
+        }
         onProgress({
             phase: "embeddings",
             message: `Generating embeddings for ${allEntries.length} entr${allEntries.length === 1 ? "y" : "ies"}.`,
@@ -94,42 +304,77 @@ export async function generateEmbeddingsForDb(db, config, onProgress, signal, en
             }
         }
         let heartbeatTimer;
+        let storedCount = 0;
+        let skippedCount = 0;
+        let embedFailedCount = 0;
+        let vecFailedCount = 0;
+        let vecUnavailableCount = 0;
+        let storedTokens = 0;
+        let lastProgressBucket = 0;
         try {
             heartbeatTimer = setInterval(() => {
                 onProgress({
                     phase: "embeddings",
-                    message: `Still generating embeddings for ${allEntries.length} entr${allEntries.length === 1 ? "y" : "ies"}; waiting on embedding provider.`,
+                    message: `Still generating embeddings: ${storedCount}/${allEntries.length} stored; waiting on embedding provider.`,
                 });
             }, 15000);
             // A failing sub-batch or an oversized document is SKIPPED by embedBatch,
             // not thrown (#874) — collect what couldn't be embedded and why, so a
             // few bad documents don't discard every other entry's embedding.
             const skips = [];
-            const embeddings = await embedBatch(texts, config.embedding, signal, (skip) => skips.push(skip));
-            throwIfAborted(signal);
-            let storedCount = 0;
-            let skippedCount = 0;
-            let embedFailedCount = 0;
-            let vecFailedCount = 0;
-            let vecUnavailableCount = 0;
-            db.transaction(() => {
-                for (const [i, entry] of allEntries.entries()) {
-                    const embedding = embeddings[i];
-                    if (!embedding) {
-                        embedFailedCount++;
-                        continue;
+            const embedStart = Date.now();
+            // Commit each provider batch in its own short transaction as it lands,
+            // rather than buffering the whole run in memory for one transaction at
+            // the very end (#954) — a competing-process lock error or any other
+            // interruption partway through now keeps whatever already committed
+            // instead of losing the entire pass.
+            // Tracks what this run actually observed, so a successful pass can
+            // record `embeddingIdentity` from real data rather than the config
+            // string alone (#955) — only the first non-empty batch's vector width
+            // is kept; every batch from one run shares the same provider/model.
+            let observedModel;
+            let observedVectorLen;
+            const onBatch = (indices, batchEmbeddings, model) => {
+                if (model)
+                    observedModel = model;
+                db.transaction(() => {
+                    for (let k = 0; k < indices.length; k++) {
+                        const entry = allEntries[indices[k]];
+                        if (!entry)
+                            continue;
+                        const embedding = batchEmbeddings[k];
+                        if (!embedding) {
+                            embedFailedCount++;
+                            continue;
+                        }
+                        if (observedVectorLen === undefined)
+                            observedVectorLen = embedding.length;
+                        const result = upsertEmbedding(db, entry.id, embedding);
+                        if (result.stored) {
+                            storedCount++;
+                            storedTokens += estimateTokenCount(entry.searchText);
+                        }
+                        else {
+                            skippedCount++;
+                        }
+                        if (result.vec === "failed")
+                            vecFailedCount++;
+                        if (result.vec === "unavailable")
+                            vecUnavailableCount++;
                     }
-                    const result = upsertEmbedding(db, entry.id, embedding);
-                    if (result.stored)
-                        storedCount++;
-                    else
-                        skippedCount++;
-                    if (result.vec === "failed")
-                        vecFailedCount++;
-                    if (result.vec === "unavailable")
-                        vecUnavailableCount++;
+                })();
+                const bucket = Math.floor(storedCount / PROGRESS_INTERVAL);
+                if (bucket > lastProgressBucket) {
+                    lastProgressBucket = bucket;
+                    onProgress({
+                        phase: "embeddings",
+                        message: `Embedded ${storedCount}/${allEntries.length} entries.`,
+                    });
                 }
-            })();
+            };
+            await embedBatch(texts, config.embedding, signal, (skip) => skips.push(skip), onBatch);
+            throwIfAborted(signal);
+            const elapsedSeconds = Math.max((Date.now() - embedStart) / 1000, 0.001);
             if (skippedCount > 0) {
                 warn(`[embed] ${skippedCount} embedding${skippedCount === 1 ? "" : "s"} skipped (entry deleted between queue and write)`);
             }
@@ -148,11 +393,16 @@ export async function generateEmbeddingsForDb(db, config, onProgress, signal, en
                     "semantic search will use the slower JS-cosine fallback over stored embeddings. " +
                     "Rebuild with 'akm index --full' after resolving the vec table (often a vector-dimension mismatch).");
             }
+            const entriesPerSec = storedCount / elapsedSeconds;
+            const tokensPerSec = storedTokens / elapsedSeconds;
             onProgress({
                 phase: "embeddings",
-                message: `Stored ${storedCount} embedding${storedCount === 1 ? "" : "s"}.`,
+                message: `Stored ${storedCount} embedding${storedCount === 1 ? "" : "s"} in ${elapsedSeconds.toFixed(1)}s (${entriesPerSec.toFixed(1)} entries/s, ~${Math.round(tokensPerSec)} tokens/s).`,
             });
             setMeta(db, "embeddingFingerprint", currentFingerprint);
+            const observedIdentity = deriveObservedEmbeddingIdentity(config.embedding, observedModel, observedVectorLen);
+            if (observedIdentity)
+                setMeta(db, "embeddingIdentity", observedIdentity);
             // Only a total failure (nothing at all embedded, despite having entries
             // to embed) turns into a phase failure. Any partial success — the vast
             // majority of a large bundle embedding fine around a handful of skips —

package/dist/indexer/search/db-search.js

@@ -25,7 +25,7 @@ import { allowsFragmentRef, defaultRendererRegistry } from "../../core/type-pres
 import { normalizeEmbeddingEndpoint } from "../../llm/embedders/remote.js";
 import { assertIndexPathReadable, closeDatabase, openExistingDatabase, } from "../../storage/repositories/index-connection.js";
 import { getAllEntries, getBaseBeliefStatesForDerivedTwins, getEntryById, getEntryCount, getPositiveFeedbackCountsByIds, } from "../../storage/repositories/index-entries-repository.js";
-import { searchFts } from "../../storage/repositories/index-fts-repository.js";
+import { getIndexedMarkdownFragment, getIndexedMarkdownFragments, searchFts, } from "../../storage/repositories/index-fts-repository.js";
 import { getMeta } from "../../storage/repositories/index-meta-repository.js";
 import { getEmbeddingCount, searchVec } from "../../storage/repositories/index-vec-repository.js";
 import { getCurrentWorkflowScopeKey } from "../../workflows/authoring/scope-key.js";
@@ -451,6 +451,14 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
     });
     const rankMs = Date.now() - tRank0;
     const selected = beliefFiltered.slice(0, limit);
+    const fragmentSelections = selected.flatMap((ranked) => ranked.fragmentId && allowsFragmentRef(ranked.entry.type) && hasIndexedProvenance(ranked)
+        ? [{ entryId: ranked.id, itemRef: ranked.itemRef, fragmentId: ranked.fragmentId }]
+        : []);
+    const selectedFragments = getIndexedMarkdownFragments(db, fragmentSelections);
+    const selectedFragmentByEntryId = new Map();
+    fragmentSelections.forEach((selection, index) => {
+        selectedFragmentByEntryId.set(selection.entryId, selectedFragments[index]);
+    });
     const hits = await Promise.all(selected.map((ranked) => {
         const { entry, filePath, score, rankingMode, utilityBoosted } = ranked;
         // CLAUDE.md locks SearchHit.score in [0,1]. The boost loop deliberately
@@ -467,6 +475,7 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
             rankingMode,
             lexicalMatch: ranked.lexicalMatch,
             fragmentId: ranked.fragmentId,
+            indexedFragment: ranked.fragmentId ? (selectedFragmentByEntryId.get(ranked.id) ?? null) : undefined,
             defaultStashDir: stashDir,
             allSourceDirs,
             sources,
@@ -788,7 +797,19 @@ export async function buildDbHit(input) {
     // The central type-presentation contract opts those types out explicitly.
     const ref = input.fragmentId && allowsFragmentRef(input.entry.type) ? `${parentRef}#${input.fragmentId}` : parentRef;
     const editable = isEditable(absolutePath, input.config, input.sources);
-    const estimatedTokens = typeof input.entry.fileSize === "number" ? Math.round(input.entry.fileSize / 4) : undefined;
+    const indexedFragment = input.indexedFragment === undefined
+        ? input.fragmentId && input.db
+            ? getIndexedMarkdownFragment(input.db, input.itemRef, input.fragmentId)
+            : undefined
+        : (input.indexedFragment ?? undefined);
+    const selectedRef = input.fragmentId && ref !== parentRef ? `${parentRef}#${input.fragmentId}` : undefined;
+    const parentEstimatedTokens = typeof input.entry.fileSize === "number"
+        ? Math.round(input.entry.fileSize / 4)
+        : indexedFragment
+            ? Math.round(indexedFragment.parentChars / 4)
+            : undefined;
+    const fragmentEstimatedTokens = indexedFragment ? Math.round(indexedFragment.fragmentChars / 4) : undefined;
+    const estimatedTokens = selectedRef === ref && fragmentEstimatedTokens !== undefined ? fragmentEstimatedTokens : parentEstimatedTokens;
     const hit = {
         type: input.entry.type,
         name: input.entry.name,
@@ -804,6 +825,32 @@ export async function buildDbHit(input) {
         score,
         whyMatched,
         ...(estimatedTokens !== undefined ? { estimatedTokens } : {}),
+        ...(selectedRef
+            ? {
+                selectedRef,
+                parentRef,
+                ...(indexedFragment
+                    ? {
+                        fragmentOrdinal: indexedFragment.ordinal + 1,
+                        fragmentCount: indexedFragment.count,
+                        startLine: indexedFragment.startLine,
+                        endLine: indexedFragment.endLine,
+                        ...(indexedFragment.previousFragmentId
+                            ? { previousRef: `${parentRef}#${indexedFragment.previousFragmentId}` }
+                            : {}),
+                        ...(indexedFragment.nextFragmentId
+                            ? { nextRef: `${parentRef}#${indexedFragment.nextFragmentId}` }
+                            : {}),
+                        fragmentChars: indexedFragment.fragmentChars,
+                        fragmentEstimatedTokens,
+                        parentChars: indexedFragment.parentChars,
+                        ...(parentEstimatedTokens !== undefined ? { parentEstimatedTokens } : {}),
+                    }
+                    : parentEstimatedTokens !== undefined
+                        ? { parentEstimatedTokens }
+                        : {}),
+            }
+            : {}),
         // Surface optional quality (v1 spec §4.2). Omitted when entry has
         // no `quality` field so payloads stay compact for the common case.
         ...(input.entry.quality ? { quality: input.entry.quality } : {}),