akm-cli 0.9.12 → 0.9.14-beta.1

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/client.js

@@ -9,11 +9,12 @@
  */
 import { fetchWithTimeout, readBodyWithByteCap } from "../core/common.js";
 import { resolveSecret } from "../core/config/config.js";
-import { ENV_REFERENCE_PATTERN } from "../core/config/schema/primitives.js";
+import { isApiKeyReference } from "../core/config/schema/primitives.js";
 import { formatExtraParamsIssue, validateExtraParams } from "../core/extra-params.js";
 import { redactErrorBody, redactSensitiveText } from "../core/redaction.js";
 import { warn, warnVerbose } from "../core/warn.js";
 import { DEFAULT_LLM_TIMEOUT_MS } from "../integrations/agent/config.js";
+import { resolveSecretFromStore } from "../sources/snapshot-fetchers/secret-seam.js";
 import { emitLlmUsage, extractUsageTokens, } from "./usage-telemetry.js";
 /** Maximum length of an upstream response excerpt included in thrown errors. */
 const ERROR_BODY_MAX_LEN = 200;
@@ -264,13 +265,16 @@ async function chatCompletionAttemptOnce(config, messages, options, timeoutMs, i
             throw new Error(formatExtraParamsIssue("LLM extraParams", issue));
     }
     const headers = { "Content-Type": "application/json" };
-    // Resolve ONLY a whole-string env reference. The execution boundary normally
-    // hands us a materialized credential after resolving `$VAR` upstream, so
-    // re-running the substitution over a literal key mangled any credential
-    // containing `$` — `sk-live$ecret` lost everything from the `$` onward, and
-    // the request failed with an opaque 401. The narrow check keeps the symbolic
-    // form working for any direct caller that still passes one.
-    const resolvedKey = ENV_REFERENCE_PATTERN.test(config.apiKey ?? "") ? resolveSecret(config.apiKey) : config.apiKey;
+    // Resolve ONLY a whole-string reference ($VAR/${VAR} or secret://<name>).
+    // The execution boundary normally hands us a materialized credential after
+    // resolving the reference upstream, so re-running the substitution over a
+    // literal key mangled any credential containing `$` — `sk-live$ecret` lost
+    // everything from the `$` onward, and the request failed with an opaque
+    // 401. The narrow check keeps the symbolic form working for any direct
+    // caller that still passes one.
+    const resolvedKey = isApiKeyReference(config.apiKey ?? "")
+        ? resolveSecret(config.apiKey, resolveSecretFromStore)
+        : config.apiKey;
     if (resolvedKey) {
         headers.Authorization = `Bearer ${resolvedKey}`;
     }

package/dist/llm/embedders/remote.js

@@ -11,6 +11,7 @@ import { fetchWithTimeout, isHttpUrl, readBodyWithByteCap } from "../../core/com
 import { resolveSecret } from "../../core/config/config.js";
 import { redactErrorBody, redactSensitiveText } from "../../core/redaction.js";
 import { warnVerbose } from "../../core/warn.js";
+import { resolveSecretFromStore } from "../../sources/snapshot-fetchers/secret-seam.js";
 /**
  * Upper bound on the number of documents in one HTTP request, independent of
  * the token budget below. Overridable via `config.batchSize`. Purely a
@@ -215,7 +216,7 @@ export class RemoteEmbedder {
     }
     buildHeaders() {
         const headers = { "Content-Type": "application/json" };
-        const resolvedKey = resolveSecret(this.config.apiKey);
+        const resolvedKey = resolveSecret(this.config.apiKey, resolveSecretFromStore);
         if (resolvedKey) {
             headers.Authorization = `Bearer ${resolvedKey}`;
         }
@@ -231,7 +232,7 @@ export class RemoteEmbedder {
      * far unredacted and uncapped, at readBodyWithByteCap's 10 MB default.
      */
     safeErrorBody(body) {
-        const resolvedKey = resolveSecret(this.config.apiKey);
+        const resolvedKey = resolveSecret(this.config.apiKey, resolveSecretFromStore);
         return redactSensitiveText(redactErrorBody(body), resolvedKey ? [resolvedKey] : []);
     }
 }

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;

package/dist/output/shapes.js

@@ -66,6 +66,51 @@ registerOutputShapes(BUILT_IN_OUTPUT_SHAPES);
  * for a soon-frozen contract, not a silent fallback to `human`).
  */
 const SHAPE_SUMMARY_COMMANDS = new Set(["show"]);
+// ── `results` collection alias ──────────────────────────────────────────────
+//
+// Every list-returning command names its collection differently (`hits`,
+// `items`, `proposals`, `sources`, ...) — a caller cannot write one accessor
+// across commands without a per-command lookup table, and the wrong guess
+// (`d.get("hits")` against a `curate` response) reads as "no results" rather
+// than "wrong key", with nothing in the envelope to correct it.
+//
+// This maps each list-returning command to the field already holding its
+// collection, and `withResultsAlias` below adds a `results` key pointing at
+// that SAME array (not a copy) to the shaped output — in every `--shape` /
+// `--detail` combination, `human` included, so `--shape agent` needs no
+// separate handling to "guarantee" it. A new list-returning command MUST add
+// an entry here; there is no way to detect a missed one automatically, so the
+// survey deliberately lives in this one place rather than scattered per
+// handler.
+const LIST_RESULT_COLLECTION_KEYS = {
+    search: "hits",
+    curate: "items",
+    "registry-search": "hits",
+    "proposal-list": "proposals",
+    list: "sources", // `akm bundle list`
+    "env-list": "envs",
+    "secret-list": "secrets",
+    "registry-list": "registries",
+    "workflow-list": "runs",
+    "task-history": "rows",
+    "log-list": "events", // `akm log list`
+};
+function withResultsAlias(command, shaped) {
+    const key = LIST_RESULT_COLLECTION_KEYS[command];
+    if (!key)
+        return shaped;
+    if (shaped === null || typeof shaped !== "object" || Array.isArray(shaped))
+        return shaped;
+    const obj = shaped;
+    if ("results" in obj)
+        return shaped;
+    const collection = obj[key];
+    if (!Array.isArray(collection))
+        return shaped;
+    // Same array reference as `obj[key]`, never a copy, so `results` cannot
+    // silently drift out of sync with the semantic key it aliases.
+    return { ...obj, results: collection };
+}
 export function shapeForCommand(command, result, detail, shape = "human") {
     let effectiveShape = shape;
     if (shape === "summary" && !SHAPE_SUMMARY_COMMANDS.has(command)) {
@@ -74,7 +119,7 @@ export function shapeForCommand(command, result, detail, shape = "human") {
     }
     const handler = getOutputShapeHandler(command);
     if (handler) {
-        return handler(result, detail, effectiveShape);
+        return withResultsAlias(command, handler(result, detail, effectiveShape));
     }
     // v1 spec §9 (output-shape registry exhaustive): no silent JSON.stringify
     // fallback. A missing case here is a registration bug — fail loudly so

package/dist/output/text/proposal-format.js

@@ -191,6 +191,7 @@ export function formatProposalDrainPlain(r) {
     const deferred = Array.isArray(r.deferred) ? r.deferred : [];
     const skippedByCap = Array.isArray(r.skippedByCap) ? r.skippedByCap : [];
     const staged = Array.isArray(r.staged) ? r.staged : [];
+    const failed = Array.isArray(r.failed) ? r.failed : [];
     const prefix = r.dryRun === true ? "[dry-run] " : "";
     const lines = [
         `${prefix}Drained proposal queue (strategy=${String(r.strategy ?? "?")}, policy=${policy}, applyMode=${applyMode})`,
@@ -199,10 +200,14 @@ export function formatProposalDrainPlain(r) {
         `  deferred: ${deferred.length}`,
         `  skippedByCap: ${skippedByCap.length}`,
         `  staged: ${staged.length}`,
+        `  failed: ${failed.length}`,
     ];
     for (const d of deferred) {
         lines.push(`    - ${String(d.id ?? "?")} (${String(d.reason ?? "?")})`);
     }
+    for (const f of failed) {
+        lines.push(`    ! ${String(f.id ?? "?")} (${String(f.reason ?? "?")}): ${String(f.detail ?? "?")}`);
+    }
     appendLoweringNotices(lines, r);
     return lines.join("\n").trimEnd();
 }