akm-cli 0.9.13 → 0.9.14-beta.1

package/dist/indexer/scan/doc-to-entry.js

@@ -34,6 +34,7 @@
  * Pure, type-only imports (no cycle participation).
  */
 import path from "node:path";
+import { getMarkdownFragmentContent, hasMarkdownFragmentContent, setMarkdownFragmentContent, } from "../passes/metadata.js";
 /**
  * Reconstruct the `IndexDocument` an `IndexDocument` was mapped from. First-class
  * IndexDocument members and the `documentJson`-carried extras are both restored;
@@ -60,6 +61,8 @@ export function indexDocumentToStashEntry(doc) {
         entry.content = doc.content;
     if (doc.contentTruncated !== undefined)
         entry.contentTruncated = doc.contentTruncated;
+    if (hasMarkdownFragmentContent(doc))
+        setMarkdownFragmentContent(entry, getMarkdownFragmentContent(doc));
     if (doc.ownsPresentation !== undefined)
         entry.ownsPresentation = doc.ownsPresentation;
     if (doc.updated !== undefined)

package/dist/indexer/scan/drain-dir.js

@@ -30,7 +30,7 @@ import path from "node:path";
 import { akmAdapter } from "../../core/adapter/adapters/akm-adapter.js";
 import { compareCodePoints } from "../../core/common.js";
 import { canonicalizeWorkflowName } from "../../core/recognition-util.js";
-import { resolveUniqueWorkflowSource, WorkflowSourceRejectionError, workflowNameForSourcePath, } from "../../workflows/source-files.js";
+import { resolveWorkflowSourceDomains, workflowNameForSourcePath } from "../../workflows/source-files.js";
 import { compileWorkflowSource } from "../../workflows/source-ir/compile.js";
 import { buildMetadataSkipWarning } from "../passes/metadata.js";
 import { buildFileContext } from "../walk/file-context.js";
@@ -53,32 +53,41 @@ export function drainDirDocuments(adapter, component, fileContexts) {
     const conceptIdByFile = new Map();
     const rejectedPaths = new Set();
     const rejectedConceptIds = new Set();
-    const workflowLookups = new Map();
-    for (const file of fileContexts) {
+    // A full directory drain may contain both peer workflow formats for one
+    // canonical ref.  Ownership arbitration must happen *before* recognition:
+    // otherwise both documents reach the persistence fold and SQLite's final
+    // row is determined by the walk/readdir order.  Resolve exactly the paths
+    // this drain owns, so a full scan retains only the deterministic `.md`
+    // winner while a targeted one-file reindex deliberately keeps its written
+    // source and therefore marks an existing peer row stale for read fallback.
+    const workflowOwnerPathByCanonicalName = new Map(resolveWorkflowSourceDomains(component.root, adapter.id, fileContexts.map((file) => file.absPath))
+        .filter((resolution) => resolution.source !== undefined)
+        .map((resolution) => [resolution.canonicalName, path.resolve(resolution.source.path)]));
+    const invalidWorkflowOwnerNames = new Set();
+    const orderedFileContexts = [...fileContexts].sort((left, right) => {
+        const leftName = workflowNameForSourcePath(component.root, adapter.id, left.absPath);
+        const rightName = workflowNameForSourcePath(component.root, adapter.id, right.absPath);
+        const leftOwner = leftName !== undefined &&
+            workflowOwnerPathByCanonicalName.get(canonicalizeWorkflowName(leftName)) === path.resolve(left.absPath);
+        const rightOwner = rightName !== undefined &&
+            workflowOwnerPathByCanonicalName.get(canonicalizeWorkflowName(rightName)) === path.resolve(right.absPath);
+        if (leftOwner !== rightOwner)
+            return leftOwner ? -1 : 1;
+        return compareCodePoints(left.absPath, right.absPath);
+    });
+    for (const file of orderedFileContexts) {
+        if (rejectedPaths.has(file.absPath))
+            continue;
         const workflowName = workflowNameForSourcePath(component.root, adapter.id, file.absPath);
         if (workflowName !== undefined) {
             const canonicalName = canonicalizeWorkflowName(workflowName);
-            if (!workflowLookups.has(canonicalName))
-                workflowLookups.set(canonicalName, workflowName);
-        }
-    }
-    for (const [canonicalName, workflowName] of [...workflowLookups].sort(([left], [right]) => compareCodePoints(left, right))) {
-        try {
-            resolveUniqueWorkflowSource(component.root, adapter.id, workflowName);
-        }
-        catch (error) {
-            if (!(error instanceof WorkflowSourceRejectionError))
-                throw error;
-            rejectedConceptIds.add(adapter.id === "akm" ? `workflows/${canonicalName}` : canonicalName);
-            for (const relativePath of error.sourcePaths) {
-                rejectedPaths.add(path.join(component.root, relativePath));
+            const ownerPath = workflowOwnerPathByCanonicalName.get(canonicalName);
+            if (ownerPath !== undefined &&
+                ownerPath !== path.resolve(file.absPath) &&
+                !invalidWorkflowOwnerNames.has(canonicalName)) {
+                continue;
             }
-            warnings.push(error.message);
         }
-    }
-    for (const file of fileContexts) {
-        if (rejectedPaths.has(file.absPath))
-            continue;
         const doc = adapter.recognize(component, file);
         if (doc === null)
             continue;
@@ -92,6 +101,8 @@ export function drainDirDocuments(adapter, component, fileContexts) {
         const dropWarning = handleWorkflowDoc(doc, file, component.root);
         if (dropWarning !== null) {
             warnings.push(dropWarning);
+            if (workflowName !== undefined)
+                invalidWorkflowOwnerNames.add(canonicalizeWorkflowName(workflowName));
             continue;
         }
         if (doc.hash !== undefined)

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

@@ -17,10 +17,11 @@ import path from "node:path";
 import { buildActionFromContributors, defaultActionContributors } from "../../core/action-contributors.js";
 import { stashDirFor } from "../../core/asset/asset-placement.js";
 import { displayRef } from "../../core/asset/resolve-ref.js";
+import { compareCodePoints } from "../../core/common.js";
 import { classifyPathAccess } from "../../core/path-access.js";
 import { getDbPath } from "../../core/paths.js";
 import { systemErrorCode } from "../../core/system-error.js";
-import { defaultRendererRegistry } from "../../core/type-presentation.js";
+import { allowsFragmentRef, defaultRendererRegistry } from "../../core/type-presentation.js";
 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";
@@ -186,13 +187,47 @@ export async function searchLocal(input) {
 }
 // ── Database search ─────────────────────────────────────────────────────────
 /**
- * Keep one deterministic ranking order before stable path deduplication. Exact
- * names survive the public score ceiling, while raw contributor differences
- * are quantized so utility-recency epsilon cannot reorder visible ties.
+ * Keep public scores in [0, 1] without flattening every boosted result to the
+ * same hard-clamped value. The ranking pipeline deliberately keeps its raw
+ * score for deterministic ordering before stable path deduplication; this
+ * monotone display projection preserves that order and leaves visible
+ * separation for graph, type, and project-context signals.
  */
+function displaySearchScore(score) {
+    return 1 - Math.exp(-Math.max(0, score));
+}
+/**
+ * A final deterministic key for genuinely tied candidates.  It deliberately
+ * excludes the asset name, filename, path, durable ref, and SQLite id: callers
+ * such as the memory-pack adapter generate each of those from an opaque source
+ * id, so using one here makes an otherwise equal search depend on that id.
+ *
+ * The normal AKM Markdown adapter keeps an H1 title in `content`; strip that
+ * one synthetic title too, because the adapter may derive it from the opaque
+ * filename.  Identical remaining bodies are semantically indistinguishable at
+ * this ranking stage and intentionally continue to the existing name/path
+ * fallback for repeatable local presentation.
+ */
+function asciiCaseFold(value) {
+    // SQLite's built-in lower() folds ASCII only unless a build opts into ICU.
+    // Keep this key deliberately in that portable shared subset instead of
+    // introducing locale-dependent JavaScript ordering for non-ASCII content.
+    return value.replace(/[A-Z]/g, (letter) => String.fromCharCode(letter.charCodeAt(0) + 32));
+}
+/** The portable byte-level title/body rule mirrored in index-fts-repository. */
+export function canonicalContentTieKey(entry) {
+    const content = entry.content ?? "";
+    const newline = content.startsWith("# ") ? content.indexOf("\n") : -1;
+    // SQLite uses ltrim(value, char(13) || char(10) || ' ') after an exact '# '
+    // title and trim(value, ' ') otherwise. Keep exactly that deliberately
+    // narrow byte contract; do not use locale or Unicode-whitespace helpers.
+    const body = newline >= 0 ? content.slice(newline + 1).replace(/^[\r\n ]+/, "") : content;
+    const source = (body || entry.description || "").replace(/^ +| +$/g, "");
+    return Buffer.from(asciiCaseFold(source), "utf8").toString("hex");
+}
 function buildSearchResultComparator(query) {
     const queryTokens = buildLexicalQueryPlan(query).tokens.map((token) => token.toLowerCase());
-    const displayScore = (score) => Math.round(Math.min(1, Math.max(0, score)) * 10000) / 10000;
+    const displayScore = (score) => Math.round(displaySearchScore(score) * 10000) / 10000;
     const stableRankScore = (score) => Math.round(score * 10000) / 10000;
     return (a, b) => {
         const aNameTier = lexicalNameMatchTier(a.entry, queryTokens);
@@ -208,11 +243,28 @@ function buildSearchResultComparator(query) {
         const rawScoreDiff = stableRankScore(b.score) - stableRankScore(a.score);
         if (rawScoreDiff !== 0)
             return rawScoreDiff;
+        // Ceiling values are intentionally allowed to demote visibility, but not
+        // to erase relevance. Prefer the score before a relaxed body-only ceiling;
+        // a later belief-state ceiling has its own minScore handoff and must not
+        // overwrite this ordering evidence. Belief-only ceilings fall back to
+        // their `preCeilingScore`.
+        const preCeilingRelevance = (item) => item.preRelaxedCeilingScore ?? item.preCeilingScore ?? item.score;
+        const ceilingDiff = stableRankScore(preCeilingRelevance(b)) - stableRankScore(preCeilingRelevance(a));
+        if (ceilingDiff !== 0)
+            return ceilingDiff;
         const nameDiff = bNameTier - aNameTier;
         if (nameDiff !== 0)
             return nameDiff;
         const typeDiff = typeBoostFor(b.entry.type) - typeBoostFor(a.entry.type);
-        return typeDiff || a.filePath.localeCompare(b.filePath);
+        if (typeDiff !== 0)
+            return typeDiff;
+        // Keep opaque generated IDs out of the final relevance tie-break.  This
+        // runs only after every ranking contributor (including the #940 preserved
+        // pre-ceiling evidence), exact-name, and type comparison has tied.
+        const contentDiff = compareCodePoints(canonicalContentTieKey(a.entry), canonicalContentTieKey(b.entry));
+        if (contentDiff !== 0)
+            return contentDiff;
+        return a.filePath.localeCompare(b.filePath);
     };
 }
 async function searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry = defaultRendererRegistry, filters, includeProposed = false, beliefFilter = "all", restrictToSources = false, includeExcludedTypes = false, disableProjectContext = false, disableScopedUtility = false) {
@@ -279,8 +331,9 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
     const { ftsResults, embeddingScores, embedMs, mode, semanticWarning } = await collectSearchSignals(db, query, limit * 3, typeFilter, defaultExcludes, config);
     const tRank0 = Date.now();
     // ── Score normalization ──────────────────────────────────────────────
-    // Normalized BM25 + cosine similarity with weighted addition
-    // (FTS 0.7, vector 0.3) for well-differentiated combined scores.
+    // Stable bounded BM25 transform + cosine similarity with weighted addition
+    // (FTS 0.7, vector 0.3). The lexical transform is per-row, so widening the
+    // candidate set cannot alter a pre-existing row's base score.
     const ftsScoreMap = normalizeFtsScores(ftsResults);
     // Build embedding score map (cosine similarities already 0-1)
     const embedScoreMap = new Map();
@@ -400,11 +453,11 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
     const selected = beliefFiltered.slice(0, limit);
     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 above can
-        // exceed 1.0 (this was a pre-existing breach that #207's graph boost
-        // — up to ~1.05 additive contribution — made detectable); clamp here
-        // so the score handed to buildDbHit always satisfies the spec.
-        const finalScore = Math.min(1, Math.max(0, score));
+        // CLAUDE.md locks SearchHit.score in [0,1]. The boost loop deliberately
+        // remains raw for ranking, then takes a monotone bounded projection at
+        // the public boundary so contributors do not collapse into hard-clamped
+        // ties.
+        const finalScore = displaySearchScore(score);
         return buildDbHit({
             entry,
             path: filePath,
@@ -413,6 +466,7 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
             query,
             rankingMode,
             lexicalMatch: ranked.lexicalMatch,
+            fragmentId: ranked.fragmentId,
             defaultStashDir: stashDir,
             allSourceDirs,
             sources,
@@ -728,7 +782,11 @@ export async function buildDbHit(input) {
         (source && path.resolve(source.path) === path.resolve(input.defaultStashDir)
             ? (input.bundleId ?? undefined)
             : undefined);
-    const ref = resolveSearchHitRef(input.entry, input, defaultBundleId);
+    const parentRef = resolveSearchHitRef(input.entry, input, defaultBundleId);
+    // Fragments prove lexical relevance, but executable assets must retain the
+    // parent ref consumed by their advertised action (for example workflow run).
+    // 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 hit = {

package/dist/indexer/search/name-match.js

@@ -0,0 +1,35 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { buildLexicalQueryPlan } from "./fts-query.js";
+/**
+ * Tokenize a display name through the same Unicode-aware lexical planner as a
+ * query.  Ranking must not invent a second, punctuation-dependent name grammar.
+ */
+export function lexicalNameTokens(name) {
+    return buildLexicalQueryPlan(name).tokens.map((token) => token.toLowerCase());
+}
+/**
+ * Structural name-token evidence. Exact tokens are always meaningful; fuzzy
+ * prefix evidence requires three code points on both sides so a question's
+ * short words or digits cannot match an opaque generated storage name.
+ */
+export function structuralNameTokenMatch(left, right) {
+    return (left === right ||
+        (Math.min([...left].length, [...right].length) >= 3 && (left.startsWith(right) || right.startsWith(left))));
+}
+/**
+ * Match a query phrase only across complete, contiguous name tokens. This is
+ * deliberately not raw substring matching: `000` must not become name
+ * evidence merely because an opaque token happens to be `z9xq000`.
+ */
+export function structuralNamePhraseMatch(nameTokens, queryTokens) {
+    if (queryTokens.length === 0 || queryTokens.length > nameTokens.length)
+        return false;
+    for (let start = 0; start <= nameTokens.length - queryTokens.length; start += 1) {
+        if (queryTokens.every((queryToken, index) => structuralNameTokenMatch(nameTokens[start + index], queryToken))) {
+            return true;
+        }
+    }
+    return false;
+}

package/dist/indexer/search/ranking-contributors.js

@@ -3,6 +3,7 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { isKnownType } from "../../core/recognition-util.js";
 import { computeGraphBoost } from "../graph/graph-boost.js";
+import { lexicalNameTokens, structuralNamePhraseMatch, structuralNameTokenMatch } from "./name-match.js";
 import { attachSearchHitAttribution } from "./search-attribution.js";
 /**
  * Chunk 1.5 (D1.5-5) — retyped from `Record<string, number>` to a FULL
@@ -105,13 +106,11 @@ function beliefStateBoost(item) {
  * stash-conventions-code-spec.md — corrections demotion).
  *
  * Why the additive {@link beliefStateBoost} penalties alone are not enough:
- * keyword base scores are min-max normalized into [0.3, 1.0]
- * (`normalizeFtsScores`), so the spread between the best FTS hit and its
- * runner-up can be as large as 0.7 — and the boost sum then MULTIPLIES the
- * base (`score *= 1 + boostSum`, {@link applyScoreContributors}). A
- * superseded incumbent that is the best keyword match for a query therefore
- * stays clamp-pinned at 1.0 above its own correction no matter what additive
- * penalty it receives — defeating the corrections pattern's point ("so the
+ * keyword base scores have a bounded lexical floor (`normalizeFtsScores`),
+ * while the boost sum then MULTIPLIES the base (`score *= 1 + boostSum`,
+ * {@link applyScoreContributors}). A superseded incumbent can still earn
+ * enough independent boosts to outrank its own correction, so additive
+ * penalties alone cannot guarantee the corrections pattern's point ("so the
  * ranker demotes the stale version instead of letting it outrank your fix").
  *
  * The ceilings guarantee the demotion while keeping flagged entries VISIBLE:
@@ -161,11 +160,10 @@ const exactNameRankingContributor = {
         if (nameBase === ctx.queryLower || nameLower === ctx.queryLower) {
             return 2.0;
         }
-        if (nameBase.includes(ctx.queryLower) || ctx.queryLower.includes(nameBase)) {
+        const nameTokens = lexicalNameTokens(nameBase);
+        if (structuralNamePhraseMatch(nameTokens, ctx.queryTokens))
             return 1.0;
-        }
-        const nameTokens = nameBase.split(/[-_\s]+/).filter(Boolean);
-        const matchCount = ctx.queryTokens.filter((qt) => nameTokens.some((nt) => nt === qt || nt.includes(qt))).length;
+        const matchCount = ctx.queryTokens.filter((qt) => nameTokens.some((nt) => structuralNameTokenMatch(nt, qt))).length;
         return matchCount > 0 ? Math.min(0.9, matchCount * 0.3) : 0;
     },
 };
@@ -245,7 +243,12 @@ const aliasRankingContributor = {
 const descriptionRankingContributor = {
     name: "description-ranking",
     appliesTo(item) {
-        return typeof item.entry.description === "string" && item.entry.description.length > 0;
+        // A relaxed FTS query admits an OR pool. Awarding a flat +0.1 merely
+        // because of a partial description coincidence double-counts a weak
+        // signal and can outrank materially stronger BM25 body evidence. The FTS
+        // score already accounts for descriptions; retain this secondary boost
+        // only for conjunctive candidates.
+        return (item.lexicalMatch !== "relaxed" && typeof item.entry.description === "string" && item.entry.description.length > 0);
     },
     adjust(item, ctx) {
         const descLower = item.entry.description?.toLowerCase() ?? "";

package/dist/indexer/search/ranking.js

@@ -1,20 +1,36 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { stableFtsScore } from "../../core/lexical-score.js";
 import { getUtilityScoresByIds } from "../../storage/repositories/index-utility-repository.js";
 import { buildLexicalQueryPlan } from "./fts-query.js";
+import { lexicalNameTokens, structuralNameTokenMatch } from "./name-match.js";
 import { applyBeliefStateScoreCeiling, applyScoreContributors, applyUtilityContributors, defaultRankingContributors, defaultUtilityRankingContributors, } from "./ranking-contributors.js";
+/**
+ * Lower bounds keep a lexical hit competitive with a vector-only neighbour;
+ * the upper bound deliberately leaves room for the ranking contributors that
+ * run after retrieval (notably the bounded graph boost).  This is a
+ * calibration for the one search pipeline, not a claim that BM25 is
+ * comparable across different queries or FTS tables.
+ */
+/**
+ * Convert FTS5's negative BM25 value into the lexical contribution used by
+ * this pipeline.  The transform is fixed and monotone: it depends only on a
+ * row's own BM25 value, so appending weaker candidates cannot rewrite an
+ * existing row's score. FTS5 commonly emits relevance near 1e-6 for broad
+ * queries, so first put relevance on a log scale around that observed value.
+ * The shape constant intentionally makes the curve approach its ceiling
+ * slowly: rare-term scores retain separation instead of all reading as 0.8.
+ *
+ * FTS5 produces finite non-positive values in normal operation.  Keeping the
+ * defensive cases here finite makes this boundary safe if a driver or fixture
+ * hands us an invalid value: `-Infinity` is the strongest possible match,
+ * while NaN, +Infinity, and positive scores contribute no lexical evidence.
+ */
 export function normalizeFtsScores(results) {
     const ftsScoreMap = new Map();
-    if (results.length === 0)
-        return ftsScoreMap;
-    const bestBm25 = results[0].bm25Score;
-    const worstBm25 = results[results.length - 1].bm25Score;
-    const range = bestBm25 - worstBm25;
     for (const result of results) {
-        const normalized = range !== 0 ? (result.bm25Score - worstBm25) / range : 1.0;
-        const ftsScore = 0.3 + normalized * 0.7;
-        ftsScoreMap.set(result.id, { score: ftsScore, result });
+        ftsScoreMap.set(result.id, { score: result.lexicalScore ?? stableFtsScore(result.bm25Score), result });
     }
     return ftsScoreMap;
 }
@@ -38,6 +54,7 @@ export function combineSearchScores(options) {
             itemRef: result.itemRef,
             bundleId: result.bundleId,
             conceptId: result.conceptId,
+            fragmentId: result.fragmentId,
         });
     }
     for (const [id, cosine] of options.embedScoreMap) {
@@ -98,9 +115,8 @@ export function applyRankingRules(options) {
         applyRelaxedLexicalScoreCeiling(item, queryTokens);
         // SPEC-5: demoting belief states (superseded/contradicted/archived/
         // deprecated) cap the FINAL score. The additive belief penalty inside the
-        // multiplicative boost sum cannot overcome the FTS min-max normalization
-        // spread, so without the ceiling a superseded incumbent that is the best
-        // keyword match outranks its own correction forever.
+        // multiplicative boost sum can still overwhelm an additive belief penalty,
+        // so without the ceiling a superseded incumbent can outrank its correction.
         applyBeliefStateScoreCeiling(item);
     }
     return options.items;
@@ -115,14 +131,12 @@ export function lexicalNameMatchTier(entry, queryTokens) {
     if (queryTokens.length === 0)
         return 0;
     const nameBase = entry.name.toLowerCase().split("/").pop() ?? entry.name.toLowerCase();
-    const nameTokens = buildLexicalQueryPlan(nameBase).tokens.map((token) => token.toLowerCase());
-    const tokenMatches = (left, right) => left === right ||
-        (Math.min([...left].length, [...right].length) >= 3 && (left.startsWith(right) || right.startsWith(left)));
+    const nameTokens = lexicalNameTokens(nameBase);
     if (nameTokens.length === queryTokens.length &&
-        nameTokens.every((token, index) => tokenMatches(token, queryTokens[index]))) {
+        nameTokens.every((token, index) => structuralNameTokenMatch(token, queryTokens[index]))) {
         return 3;
     }
-    const matched = queryTokens.filter((token) => nameTokens.some((nameToken) => tokenMatches(nameToken, token))).length;
+    const matched = queryTokens.filter((token) => nameTokens.some((nameToken) => structuralNameTokenMatch(nameToken, token))).length;
     if (matched === queryTokens.length)
         return 2;
     return matched > 0 ? 1 : 0;
@@ -130,10 +144,20 @@ export function lexicalNameMatchTier(entry, queryTokens) {
 /**
  * A relaxed OR query admits intentionally weak candidates. Candidates with no
  * query token in their name remain visible for body-only recall, but cannot
- * saturate at the same displayed score as stronger name-bearing recoveries.
+ * share the same bounded displayed score as stronger name-bearing recoveries.
+ * The raw ceiling is 0.65; the public score projection is applied later, so
+ * callers never literally receive `0.65` just because this ceiling bound.
+ *
+ * Preserve the pre-ceiling relevance separately from `preCeilingScore`, which
+ * belongs to belief-state demotion and may be written afterwards. A relaxed,
+ * belief-demoted candidate otherwise loses both its body relevance and its
+ * ordering signal when the second ceiling overwrites the first.
  */
 function applyRelaxedLexicalScoreCeiling(item, queryTokens) {
     if (item.lexicalMatch !== "relaxed" || lexicalNameMatchTier(item.entry, queryTokens) > 0)
         return;
-    item.score = Math.min(item.score, RELAXED_NON_NAME_SCORE_CEILING);
+    if (item.score > RELAXED_NON_NAME_SCORE_CEILING) {
+        item.preRelaxedCeilingScore = item.score;
+        item.score = RELAXED_NON_NAME_SCORE_CEILING;
+    }
 }

package/dist/indexer/usage/show-usage.js

@@ -22,6 +22,18 @@ export function recentShowCount(ref) {
         return 0;
     }
 }
+/** Compare search/display selectors by their durable parent asset identity. */
+function traceParentRef(ref) {
+    try {
+        const parsed = parseBundleRef(ref);
+        return makeBundleRef(parsed.bundle, parsed.conceptId);
+    }
+    catch {
+        // Registry result refs are not local bundle refs and cannot have a local
+        // selector. Keep their existing exact comparison behavior.
+        return ref;
+    }
+}
 function appendShowTrace(ref, type, name) {
     appendEvent({ eventType: "show", ref, metadata: { type, name } });
     try {
@@ -34,7 +46,7 @@ function appendShowTrace(ref, type, name) {
             if (!event.ts || new Date(event.ts).getTime() < cutoffMs)
                 return false;
             const refs = event.metadata?.resultRefs ?? [];
-            return refs.includes(ref);
+            return refs.some((candidate) => traceParentRef(candidate) === ref);
         });
         if (!matchingSearch)
             return;
@@ -45,7 +57,7 @@ function appendShowTrace(ref, type, name) {
             metadata: {
                 query: matchingSearch.metadata?.query,
                 searchTs: matchingSearch.ts,
-                rankPosition: resultRefs.indexOf(ref),
+                rankPosition: resultRefs.findIndex((candidate) => traceParentRef(candidate) === ref),
             },
         });
     }

package/dist/llm/graph-extract.js

@@ -20,6 +20,7 @@
  */
 import systemPromptTemplate from "../assets/prompts/graph-extract-system.md" with { type: "text" };
 import userPromptTemplate from "../assets/prompts/graph-extract-user-prompt.md" with { type: "text" };
+import { splitMarkdownFragmentStats } from "../core/asset/markdown-fragments.js";
 import { toErrorMessage } from "../core/common.js";
 import { ConfigError } from "../core/errors.js";
 import { parseEmbeddedJsonResponse } from "../core/parse.js";
@@ -117,79 +118,29 @@ function normalizeBatchState(state) {
     state.nonArrayBatchFailures = Math.max(0, state.nonArrayBatchFailures ?? 0);
     return state;
 }
-function splitParagraph(text, maxChars) {
-    if (text.length <= maxChars)
-        return { chunks: [text], truncationCount: 0 };
-    const chunks = [];
-    let truncationCount = 0;
-    let remaining = text;
-    while (remaining.length > maxChars) {
-        let splitAt = remaining.lastIndexOf(" ", maxChars);
-        if (splitAt < Math.floor(maxChars * 0.6))
-            splitAt = maxChars;
-        const piece = remaining.slice(0, splitAt).trim();
-        if (piece)
-            chunks.push(piece);
-        remaining = remaining.slice(splitAt).trim();
-        truncationCount += 1;
-    }
-    if (remaining)
-        chunks.push(remaining);
-    return { chunks, truncationCount };
-}
 function splitBodyIntoChunks(body, maxChars = MAX_CHUNK_BODY_CHARS) {
-    const sections = body
-        .split(/\n(?=#{1,6}\s)/)
-        .map((section) => section.trim())
-        .filter(Boolean);
-    if (sections.length === 0)
-        return { chunks: [body.trim()].filter(Boolean), truncationCount: 0 };
+    const split = splitMarkdownFragmentStats(body, maxChars);
+    // Graph extraction keeps its historical cost shape: adjacent safe fragments
+    // share one LLM call whenever they fit. The fragment splitter is still the
+    // sole boundary authority; this is only prompt packing, never a second
+    // parser/chunker. Hard splits stay isolated and telemetry remains the core
+    // split count rather than counting ordinary heading boundaries.
     const chunks = [];
     let current = "";
-    let truncationCount = 0;
-    const flush = () => {
-        const trimmed = current.trim();
-        if (trimmed)
-            chunks.push(trimmed);
-        current = "";
-    };
-    for (const section of sections) {
-        if (section.length <= maxChars) {
-            const candidate = current ? `${current}\n\n${section}` : section;
-            if (candidate.length <= maxChars)
-                current = candidate;
-            else {
-                flush();
-                current = section;
-            }
-            continue;
+    for (const fragment of split.fragments) {
+        const candidate = current ? `${current}\n\n${fragment.text}` : fragment.text;
+        if (candidate.length <= maxChars) {
+            current = candidate;
         }
-        const paragraphs = section
-            .split(/\n\s*\n/)
-            .map((part) => part.trim())
-            .filter(Boolean);
-        for (const paragraph of paragraphs) {
-            if (paragraph.length <= maxChars) {
-                const candidate = current ? `${current}\n\n${paragraph}` : paragraph;
-                if (candidate.length <= maxChars)
-                    current = candidate;
-                else {
-                    flush();
-                    current = paragraph;
-                }
-                continue;
-            }
-            flush();
-            const split = splitParagraph(paragraph, maxChars);
-            truncationCount += split.truncationCount;
-            for (const piece of split.chunks) {
-                if (piece.length <= maxChars)
-                    chunks.push(piece);
-            }
+        else {
+            if (current)
+                chunks.push(current);
+            current = fragment.text;
         }
     }
-    flush();
-    return { chunks, truncationCount };
+    if (current)
+        chunks.push(current);
+    return { chunks, truncationCount: split.hardSplitCount };
 }
 /** Consistency weight for blending chunk-agreement with LLM confidence. */
 const CONSISTENCY_WEIGHT = 0.4;