akm-cli 0.9.16 → 0.9.17-alpha.10

package/dist/indexer/passes/metadata.js

@@ -125,13 +125,8 @@ export function validateStashEntry(entry) {
         result.cwd = e.cwd.trim();
     if (typeof e.fileSize === "number" && Number.isFinite(e.fileSize) && e.fileSize >= 0)
         result.fileSize = e.fileSize;
-    if (e.wikiRole === "schema" ||
-        e.wikiRole === "index" ||
-        e.wikiRole === "log" ||
-        e.wikiRole === "raw" ||
-        e.wikiRole === "page") {
+    if (isWikiRole(e.wikiRole))
         result.wikiRole = e.wikiRole;
-    }
     if (typeof e.pageKind === "string" && e.pageKind.trim().length > 0) {
         result.pageKind = e.pageKind.trim();
     }
@@ -155,12 +150,6 @@ export function validateStashEntry(entry) {
     const contradictedBy = normalizeNonEmptyStringList(e.contradictedBy);
     if (contradictedBy)
         result.contradictedBy = contradictedBy;
-    // R5 — consolidation provenance fields must survive the whitelist too, or
-    // stash.json-overridden merge products lose merge-following + generation
-    // counting in the collapse detector.
-    if (typeof e.generation === "number" && Number.isFinite(e.generation) && e.generation > 0) {
-        result.generation = Math.floor(e.generation);
-    }
     const currentBeliefRefs = normalizeNonEmptyStringList(e.currentBeliefRefs);
     if (currentBeliefRefs)
         result.currentBeliefRefs = currentBeliefRefs;
@@ -269,9 +258,6 @@ function normalizeIntent(value) {
         intent.output = output;
     return Object.keys(intent).length > 0 ? intent : undefined;
 }
-function normalizeStringListOrUndefined(value) {
-    return normalizeNonEmptyStringList(value);
-}
 /**
  * Normalize a current derived-memory parent ref to its `memories/<name>`
  * conceptId for the `derived_from` column. Returns `undefined` for a non-memory
@@ -318,19 +304,19 @@ export function applyCuratedFrontmatter(entry, fmData) {
         entry.source = "frontmatter";
         entry.confidence = 0.9;
     }
-    const tags = normalizeStringListOrUndefined(fmData.tags);
+    const tags = normalizeNonEmptyStringList(fmData.tags);
     if (tags)
         entry.tags = normalizeTerms(tags);
-    const aliases = normalizeStringListOrUndefined(fmData.aliases);
+    const aliases = normalizeNonEmptyStringList(fmData.aliases);
     if (aliases)
         entry.aliases = normalizeTerms(aliases);
-    const searchHints = normalizeStringListOrUndefined(fmData.searchHints);
+    const searchHints = normalizeNonEmptyStringList(fmData.searchHints);
     if (searchHints)
         entry.searchHints = searchHints;
-    const usage = normalizeStringListOrUndefined(fmData.usage);
+    const usage = normalizeNonEmptyStringList(fmData.usage);
     if (usage)
         entry.usage = usage;
-    const examples = normalizeStringListOrUndefined(fmData.examples);
+    const examples = normalizeNonEmptyStringList(fmData.examples);
     if (examples)
         entry.examples = examples;
     const run = asNonEmptyString(fmData.run);
@@ -354,19 +340,13 @@ export function applyCuratedFrontmatter(entry, fmData) {
     const beliefState = asNonEmptyString(fmData.beliefState);
     if (beliefState)
         entry.beliefState = beliefState;
-    const supersededBy = normalizeStringListOrUndefined(fmData.supersededBy);
+    const supersededBy = normalizeNonEmptyStringList(fmData.supersededBy);
     if (supersededBy)
         entry.supersededBy = supersededBy;
-    const contradictedBy = normalizeStringListOrUndefined(fmData.contradictedBy);
+    const contradictedBy = normalizeNonEmptyStringList(fmData.contradictedBy);
     if (contradictedBy)
         entry.contradictedBy = contradictedBy;
-    // R5 — consolidation generation depth is captured so the collapse detector
-    // can count over-generation assets without filesystem reads.
-    const generation = fmData.generation;
-    if (typeof generation === "number" && Number.isFinite(generation) && generation > 0) {
-        entry.generation = Math.floor(generation);
-    }
-    const currentBeliefRefs = normalizeStringListOrUndefined(fmData.currentBeliefRefs);
+    const currentBeliefRefs = normalizeNonEmptyStringList(fmData.currentBeliefRefs);
     if (currentBeliefRefs)
         entry.currentBeliefRefs = currentBeliefRefs;
     // captureMode: "hot" | "background" — strict whitelist; unknown values are ignored.
@@ -384,7 +364,7 @@ export function applyCuratedFrontmatter(entry, fmData) {
     else if (typeof fmData.lessonStrength === "number" && Number.isFinite(fmData.lessonStrength)) {
         entry.lessonStrength = Math.max(0, Math.floor(fmData.lessonStrength));
     }
-    const evidenceSources = normalizeStringListOrUndefined(fmData.evidenceSources);
+    const evidenceSources = normalizeNonEmptyStringList(fmData.evidenceSources);
     if (evidenceSources)
         entry.evidenceSources = evidenceSources;
     // Phase 5A / Advantage D5: capture parent ref for derived memories.
@@ -456,30 +436,22 @@ export function extractCommandParameters(template) {
  * frontmatter block and apply them to the entry. Tolerates missing or malformed values.
  */
 export function applyWikiFrontmatter(entry, fmData) {
-    const role = fmData.wikiRole;
-    if (role === "schema" || role === "index" || role === "log" || role === "raw" || role === "page") {
-        entry.wikiRole = role;
-    }
+    if (isWikiRole(fmData.wikiRole))
+        entry.wikiRole = fmData.wikiRole;
     const pageKind = fmData.pageKind;
     if (typeof pageKind === "string" && pageKind.trim().length > 0) {
         entry.pageKind = pageKind.trim();
     }
-    const xrefs = fmData.xrefs;
-    if (Array.isArray(xrefs)) {
-        const filtered = xrefs
-            .filter((x) => typeof x === "string" && x.trim().length > 0)
-            .map((x) => x.trim());
-        if (filtered.length > 0)
-            entry.xrefs = filtered;
-    }
-    const sources = fmData.sources;
-    if (Array.isArray(sources)) {
-        const filtered = sources
-            .filter((s) => typeof s === "string" && s.trim().length > 0)
-            .map((s) => s.trim());
-        if (filtered.length > 0)
-            entry.sources = filtered;
-    }
+    // Only lists: a bare string is not a citation list here.
+    const xrefs = Array.isArray(fmData.xrefs) ? normalizeNonEmptyStringList(fmData.xrefs) : undefined;
+    if (xrefs)
+        entry.xrefs = xrefs;
+    const sources = Array.isArray(fmData.sources) ? normalizeNonEmptyStringList(fmData.sources) : undefined;
+    if (sources)
+        entry.sources = sources;
+}
+function isWikiRole(value) {
+    return value === "schema" || value === "index" || value === "log" || value === "raw" || value === "page";
 }
 /**
  * Parse one `verified:` family value into the `IndexDocument.provenance` shape.
@@ -679,6 +651,26 @@ function parseIntentCommentLine(cleaned, metadata) {
         metadata.intent.when ??= value;
     return true;
 }
+/** `@tag value` comment lines, in match order; the first matching tag wins a line. */
+const COMMENT_TAGS = [
+    [/^@description\s+(.+)$/, (m, v) => (m.description = v.trim())],
+    [/^@tags?\s+(.+)$/, (m, v) => (m.tags = splitCommentList(v))],
+    [/^@aliases?\s+(.+)$/, (m, v) => (m.aliases = splitCommentList(v))],
+    [/^@searchHints?\s+(.+)$/, (m, v) => (m.searchHints = splitCommentList(v))],
+    [/^@usage\s+(.+)$/, (m, v) => (m.usage = [...(m.usage ?? []), v.trim()])],
+    [/^@examples?\s+(.+)$/, (m, v) => (m.examples = [...(m.examples ?? []), v.trim()])],
+    [/^@run\s+(.+)$/, (m, v) => (m.run = v.trim())],
+    [/^@setup\s+(.+)$/, (m, v) => (m.setup = v.trim())],
+    [/^@cwd\s+(.+)$/, (m, v) => (m.cwd = v.trim())],
+    [
+        /^@scope\s+(.+)$/,
+        (m, v) => {
+            const scope = parseCommentScope(v);
+            if (scope)
+                m.scope = scope;
+        },
+    ],
+];
 export function extractCommentMetadata(filePath, content) {
     if (content === undefined) {
         try {
@@ -702,56 +694,12 @@ export function extractCommentMetadata(filePath, content) {
             continue;
         if (parseIntentCommentLine(cleaned, metadata))
             continue;
-        const descMatch = cleaned.match(/^@description\s+(.+)$/);
-        if (descMatch) {
-            metadata.description = descMatch[1].trim();
-            continue;
-        }
-        const tagsMatch = cleaned.match(/^@tags?\s+(.+)$/);
-        if (tagsMatch) {
-            metadata.tags = splitCommentList(tagsMatch[1]);
-            continue;
-        }
-        const aliasesMatch = cleaned.match(/^@aliases?\s+(.+)$/);
-        if (aliasesMatch) {
-            metadata.aliases = splitCommentList(aliasesMatch[1]);
-            continue;
-        }
-        const hintsMatch = cleaned.match(/^@searchHints?\s+(.+)$/);
-        if (hintsMatch) {
-            metadata.searchHints = splitCommentList(hintsMatch[1]);
-            continue;
-        }
-        const usageMatch = cleaned.match(/^@usage\s+(.+)$/);
-        if (usageMatch) {
-            metadata.usage = [...(metadata.usage ?? []), usageMatch[1].trim()];
-            continue;
-        }
-        const examplesMatch = cleaned.match(/^@examples?\s+(.+)$/);
-        if (examplesMatch) {
-            metadata.examples = [...(metadata.examples ?? []), examplesMatch[1].trim()];
-            continue;
-        }
-        const runMatch = cleaned.match(/^@run\s+(.+)$/);
-        if (runMatch) {
-            metadata.run = runMatch[1].trim();
-            continue;
-        }
-        const setupMatch = cleaned.match(/^@setup\s+(.+)$/);
-        if (setupMatch) {
-            metadata.setup = setupMatch[1].trim();
-            continue;
-        }
-        const cwdMatch = cleaned.match(/^@cwd\s+(.+)$/);
-        if (cwdMatch) {
-            metadata.cwd = cwdMatch[1].trim();
-            continue;
-        }
-        const scopeMatch = cleaned.match(/^@scope\s+(.+)$/);
-        if (scopeMatch) {
-            const scope = parseCommentScope(scopeMatch[1]);
-            if (scope)
-                metadata.scope = scope;
+        for (const [pattern, apply] of COMMENT_TAGS) {
+            const match = cleaned.match(pattern);
+            if (match) {
+                apply(metadata, match[1]);
+                break;
+            }
         }
     }
     return Object.keys(metadata).length > 0 ? metadata : undefined;
@@ -760,50 +708,32 @@ export function applyCommentMetadata(entry, metadata) {
     if (!metadata)
         return;
     let usedCommentMetadata = false;
-    if (metadata.description && !entry.description) {
-        entry.description = metadata.description;
-        usedCommentMetadata = true;
-    }
-    if (metadata.tags?.length && (!entry.tags || entry.tags.length === 0)) {
-        entry.tags = normalizeTerms(metadata.tags);
-        usedCommentMetadata = true;
-    }
-    if (metadata.aliases?.length) {
-        entry.aliases = normalizeTerms(metadata.aliases);
-        usedCommentMetadata = true;
-    }
-    if (metadata.searchHints?.length) {
-        entry.searchHints = metadata.searchHints;
-        usedCommentMetadata = true;
-    }
-    if (metadata.usage?.length) {
-        entry.usage = metadata.usage;
-        usedCommentMetadata = true;
-    }
-    if (metadata.examples?.length) {
-        entry.examples = metadata.examples;
-        usedCommentMetadata = true;
-    }
-    if (metadata.intent && Object.keys(metadata.intent).length > 0) {
-        entry.intent = metadata.intent;
+    const use = (key, value) => {
+        entry[key] = value;
         usedCommentMetadata = true;
-    }
-    if (metadata.run) {
-        entry.run = metadata.run;
-        usedCommentMetadata = true;
-    }
-    if (metadata.setup) {
-        entry.setup = metadata.setup;
-        usedCommentMetadata = true;
-    }
-    if (metadata.cwd) {
-        entry.cwd = metadata.cwd;
-        usedCommentMetadata = true;
-    }
-    if (metadata.scope) {
-        entry.scope = metadata.scope;
-        usedCommentMetadata = true;
-    }
+    };
+    if (metadata.description && !entry.description)
+        use("description", metadata.description);
+    if (metadata.tags?.length && (!entry.tags || entry.tags.length === 0))
+        use("tags", normalizeTerms(metadata.tags));
+    if (metadata.aliases?.length)
+        use("aliases", normalizeTerms(metadata.aliases));
+    if (metadata.searchHints?.length)
+        use("searchHints", metadata.searchHints);
+    if (metadata.usage?.length)
+        use("usage", metadata.usage);
+    if (metadata.examples?.length)
+        use("examples", metadata.examples);
+    if (metadata.intent && Object.keys(metadata.intent).length > 0)
+        use("intent", metadata.intent);
+    if (metadata.run)
+        use("run", metadata.run);
+    if (metadata.setup)
+        use("setup", metadata.setup);
+    if (metadata.cwd)
+        use("cwd", metadata.cwd);
+    if (metadata.scope)
+        use("scope", metadata.scope);
     if (usedCommentMetadata && entry.source !== "frontmatter" && entry.source !== "manual") {
         entry.source = "comments";
         entry.confidence = Math.max(entry.confidence ?? 0, 0.7);
@@ -813,25 +743,6 @@ function mergeAliases(existing, generated) {
     const merged = normalizeTerms([...(existing ?? []), ...generated]);
     return merged.length > 0 ? merged : undefined;
 }
-// ── Enrichment Completeness ─────────────────────────────────────────────────
-/**
- * Returns `true` when a stash entry already has enough LLM-quality metadata
- * that calling the LLM would produce no meaningful improvement.
- *
- * An entry is considered complete when ALL of the following hold:
- * - `description` is a non-empty string
- * - `tags` is a non-empty array
- * - `searchHints` is a non-empty array
- *
- * This predicate is used by `enhanceDirsWithLlm` to skip the LLM call for
- * entries that were previously enriched and already carry all three fields.
- */
-export function isEnrichmentComplete(entry) {
-    const hasDescription = typeof entry.description === "string" && entry.description.trim().length > 0;
-    const hasTags = Array.isArray(entry.tags) && entry.tags.length > 0;
-    const hasSearchHints = Array.isArray(entry.searchHints) && entry.searchHints.length > 0;
-    return hasDescription && hasTags && hasSearchHints;
-}
 // ── Native Markdown search projection ──────────────────────────────────────
 /**
  * Maximum native Markdown prose carried by the low-weight `content` field.
@@ -1131,36 +1042,14 @@ export function projectMarkdownContent(body, truncationInfo) {
     const innerBlock = findInnerFrontmatterBlock(lines);
     const start = innerBlock && isFrontmatterShaped(lines, innerBlock) ? innerBlock.close + 1 : 0;
     const projected = [];
-    let fence;
-    const htmlComment = { inComment: false };
-    for (let i = start; i < lines.length; i += 1) {
-        const rawLine = lines[i];
-        if (fence) {
-            if (isMarkdownFenceClosing(rawLine, fence))
-                fence = undefined;
-            continue;
-        }
-        // A leading fence owns the whole line, including any info string that
-        // resembles HTML. Comment state therefore cannot begin inside a fence.
-        if (!htmlComment.inComment) {
-            const openingFence = parseMarkdownFenceOpening(rawLine);
-            if (openingFence) {
-                fence = openingFence;
-                continue;
-            }
-        }
-        let trimmed = stripMarkdownHtmlComments(rawLine, htmlComment).trim();
-        const openingFence = parseMarkdownFenceOpening(trimmed);
-        if (openingFence) {
-            fence = openingFence;
-            continue;
-        }
+    forEachVisibleMarkdownLine(lines, start, (_index, visible) => {
+        let trimmed = visible.trim();
         if (!trimmed || /^(-{3,}|\*{3,}|_{3,}|=+)$/.test(trimmed))
-            continue;
+            return;
         if (/^\s*\[[^\]]+\]:\s*\S+/.test(trimmed))
-            continue;
+            return;
         if (/^<[^>]+>$/.test(trimmed))
-            continue;
+            return;
         // Preserve human-facing labels and inline identifiers, never destinations.
         trimmed = stripMarkdownLinkDestinations(trimmed);
         trimmed = trimmed.replace(/`{1,2}([^`]+)`{1,2}/g, "$1");
@@ -1171,7 +1060,7 @@ export function projectMarkdownContent(body, truncationInfo) {
         trimmed = trimmed.replace(/\s+/g, " ").trim();
         if (trimmed)
             projected.push(trimmed);
-    }
+    });
     const text = projected.join(" ").replace(/\s+/g, " ").trim();
     if (!text)
         return undefined;
@@ -1179,6 +1068,36 @@ export function projectMarkdownContent(body, truncationInfo) {
         truncationInfo.truncated = text.length > MARKDOWN_CONTENT_MAX_CHARS;
     return truncateUnicodeSafe(text, MARKDOWN_CONTENT_MAX_CHARS);
 }
+/**
+ * Visit each line from `start` that lies outside fenced code, with HTML
+ * comments removed (`visible`); fence lines themselves are never visited.
+ */
+function forEachVisibleMarkdownLine(lines, start, visit) {
+    let fence;
+    const htmlComment = { inComment: false };
+    for (let index = start; index < lines.length; index += 1) {
+        const rawLine = lines[index];
+        if (fence) {
+            if (isMarkdownFenceClosing(rawLine, fence))
+                fence = undefined;
+            continue;
+        }
+        // A leading fence owns the whole line, including any info string that
+        // resembles HTML. Comment state therefore cannot begin inside a fence.
+        const leadingFence = htmlComment.inComment ? undefined : parseMarkdownFenceOpening(rawLine);
+        if (leadingFence) {
+            fence = leadingFence;
+            continue;
+        }
+        const visible = stripMarkdownHtmlComments(rawLine, htmlComment);
+        const openingFence = parseMarkdownFenceOpening(visible.trim());
+        if (openingFence) {
+            fence = openingFence;
+            continue;
+        }
+        visit(index, visible);
+    }
+}
 // Fragment text is intentionally not an IndexDocument field. IndexDocument is
 // an adapter/search payload boundary; this is an internal, derived index input
 // that is persisted separately by the entries repository for deterministic FTS
@@ -1197,6 +1116,21 @@ export function getMarkdownFragmentContent(entry) {
 export function hasMarkdownFragmentContent(entry) {
     return markdownFragmentProjectionEntries.has(entry);
 }
+/**
+ * A copy of `entry` carrying `filePath`'s size (and its fragment projection),
+ * or `entry` itself when the file cannot be stat'ed.
+ */
+export function withFileSize(entry, filePath) {
+    try {
+        const sized = { ...entry, fileSize: fs.statSync(filePath).size };
+        if (hasMarkdownFragmentContent(entry))
+            setMarkdownFragmentContent(sized, getMarkdownFragmentContent(entry));
+        return sized;
+    }
+    catch {
+        return entry;
+    }
+}
 /**
  * Produce a safe, structure-preserving projection for fragment indexing.
  * Excluded source lines are retained as blank lines so fragment locations map
@@ -1206,37 +1140,16 @@ export function hasMarkdownFragmentContent(entry) {
 export function projectMarkdownFragmentContent(raw) {
     const lines = raw.split(/\r?\n/);
     const parsed = parseFrontmatter(raw);
-    const start = parsed.frontmatter ? parsed.bodyStartLine - 1 : 0;
     const projected = lines.map(() => "");
-    let fence;
-    const htmlComment = { inComment: false };
-    for (let index = start; index < lines.length; index++) {
-        const rawLine = lines[index];
-        if (fence) {
-            if (isMarkdownFenceClosing(rawLine, fence))
-                fence = undefined;
-            continue;
-        }
-        if (!htmlComment.inComment) {
-            const opening = parseMarkdownFenceOpening(rawLine);
-            if (opening) {
-                fence = opening;
-                continue;
-            }
-        }
-        let safe = stripMarkdownHtmlComments(rawLine, htmlComment);
-        const opening = parseMarkdownFenceOpening(safe.trim());
-        if (opening) {
-            fence = opening;
-            continue;
-        }
+    forEachVisibleMarkdownLine(lines, parsed.frontmatter ? parsed.bodyStartLine - 1 : 0, (index, visible) => {
         // Reference link destinations and standalone HTML are not retrieval
         // evidence and can contain credential-bearing URLs.
-        if (/^\s*\[[^\]]+\]:\s*\S+/.test(safe) || /^\s*<[^>]+>\s*$/.test(safe))
-            continue;
-        safe = stripMarkdownLinkDestinations(safe).replace(/<[^>]+>/g, " ");
-        projected[index] = safe.replace(/[ \t]+$/g, "");
-    }
+        if (/^\s*\[[^\]]+\]:\s*\S+/.test(visible) || /^\s*<[^>]+>\s*$/.test(visible))
+            return;
+        projected[index] = stripMarkdownLinkDestinations(visible)
+            .replace(/<[^>]+>/g, " ")
+            .replace(/[ \t]+$/g, "");
+    });
     const text = projected.join("\n");
     return text.trim() ? text : undefined;
 }
@@ -1350,7 +1263,7 @@ export function applyPostContributorFields(entry, file, canonicalName, dirPath)
     entry.tags = [...(entry.tags ?? []), ...extractDirTagsFromName(canonicalName)];
     entry.tags = normalizeTerms(entry.tags ?? []);
     entry.aliases = mergeAliases(entry.aliases, buildAliases(canonicalName, entry.tags));
-    // Search hints are only generated when LLM is configured (via enhanceStashWithLlm)
+    // Search hints are only generated when LLM is configured (via enhanceEntriesWithLlm)
     // Heuristic search hints are too noisy to be useful for search quality
     entry.filename = path.basename(file);
 }

package/dist/indexer/read-preflight.js

@@ -14,10 +14,3 @@ export async function ensurePrimaryIndexForRead(primarySource) {
         return false;
     return ensureIndex(primarySource.path);
 }
-/**
- * Convenience helper for callers that only need to ensure a read index from a
- * configured stash path and default config.
- */
-export async function ensurePrimaryIndexFromConfig(overrideStashDir, existingConfig) {
-    return ensurePrimaryIndexForRead(resolveReadSources(overrideStashDir, existingConfig).primarySource);
-}

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

@@ -27,7 +27,7 @@
  *     `basename(file)` in `applyPostContributorFields`, and `doc.path` IS that
  *     file, so the value is identical.
  *   - `fileSize` — never set by `recognize` NOR by the legacy flat-walk pass;
- *     both pipelines attach it at PERSIST time (`attachFileSize`). It is therefore
+ *     both pipelines attach it at PERSIST time (`withFileSize`). It is therefore
  *     intentionally absent here and added by the persist layer, exactly as
  *     before.
  *
@@ -137,9 +137,8 @@ export function indexDocumentToStashEntry(doc) {
     if (dj.wikiRole !== undefined)
         entry.wikiRole = dj.wikiRole;
     assignStringList(entry, "sources", dj.sources);
-    if (typeof dj.generation === "number")
-        entry.generation = dj.generation;
     assignStringList(entry, "evidenceSources", dj.evidenceSources);
+    assignStringList(entry, "uses", dj.uses);
     // D2 (#730): OKF v0.2 provenance promoteProposal stamps onto AKM-native
     // writes, carried via DOCUMENT_JSON_CARRIED_FIELDS (akm-adapter.ts) —
     // unpacked back to a first-class member here exactly like `sources`/

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

@@ -30,8 +30,8 @@ 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 { compileWorkflowSource } from "../../workflows/compile.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";
 import { indexDocumentToStashEntry } from "./doc-to-entry.js";