akm-cli 0.9.17-alpha.7 → 0.9.17-alpha.9

package/dist/indexer/links/declared-links.js

@@ -0,0 +1,90 @@
+// 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 { stashDirFor } from "../../core/asset/asset-placement.js";
+import { isBundleSlug, parseBundleRef } from "../../core/asset/asset-ref.js";
+/** Channel order is the order links are stored and shown in. */
+const CHANNELS = [
+    ["xref", (doc) => doc.xrefs],
+    ["superseded_by", (doc) => doc.supersededBy],
+    ["contradicted_by", (doc) => doc.contradictedBy],
+    ["belief_peer", (doc) => doc.currentBeliefRefs],
+    ["derived_from", (doc) => doc.derivedFrom],
+    ["cites", (doc) => doc.sources],
+    ["links_to", (doc) => doc.links],
+    ["uses", (doc) => doc.uses],
+];
+/** The links an indexed document declares, in channel then authored order; one per (kind, target). */
+export function declaredLinks(doc, owner) {
+    const links = [];
+    const seen = new Set();
+    for (const [kind, read] of CHANNELS) {
+        for (const raw of stringValues(read(doc))) {
+            const target = linkTarget(raw, owner.conceptId);
+            if (!target)
+                continue;
+            const bundle = target.bundle ?? owner.bundleId;
+            if (bundle === owner.bundleId && target.conceptId === owner.conceptId)
+                continue;
+            const key = `${kind}\0${bundle}\0${target.conceptId}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            links.push({ kind, raw, ...target });
+        }
+    }
+    return links;
+}
+function stringValues(value) {
+    if (typeof value === "string")
+        return [value];
+    return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+/**
+ * The target a token names, or `undefined` when the token is not an asset ref
+ * (a session id, a URL, prose, a template placeholder). Retired spellings
+ * convert in memory: `<type>:<name>` (`memory:x`), `wiki:<wiki>/<path>` (0.8
+ * wikis, now knowledge under `wikis/`), a `.md` suffix, and a `#fragment`.
+ * Inside a wiki page, `raw/…` and `pages/…` are relative to the wiki root.
+ */
+function linkTarget(raw, ownerConceptId) {
+    const token = raw.trim();
+    if (!token || /[\s<*]/.test(token) || token.includes("$(") || token.includes("${"))
+        return;
+    let bundle;
+    let body = token;
+    const boundary = token.indexOf("//");
+    if (boundary >= 0) {
+        bundle = token.slice(0, boundary);
+        body = token.slice(boundary + 2);
+        if (!isBundleSlug(bundle))
+            return;
+    }
+    const conceptId = legacyConceptId(body.split("#", 1)[0] ?? "", ownerConceptId);
+    if (conceptId === undefined || conceptId.length <= 1 || conceptId.includes("//"))
+        return;
+    try {
+        return { ...(bundle ? { bundle } : {}), conceptId: parseBundleRef(conceptId).conceptId };
+    }
+    catch {
+        return;
+    }
+}
+function legacyConceptId(body, ownerConceptId) {
+    const stripped = body.replace(/\.md$/i, "");
+    const colon = stripped.indexOf(":");
+    if (colon >= 0) {
+        const type = stripped.slice(0, colon);
+        const name = stripped.slice(colon + 1);
+        if (!name || name.includes(":"))
+            return;
+        if (type === "wiki")
+            return `knowledge/wikis/${name}`;
+        const stashDir = stashDirFor(type);
+        return stashDir === undefined ? undefined : `${stashDir}/${name}`;
+    }
+    const wikiRoot = /^((?:[^/]+\/)*?wikis\/[^/]+\/)/.exec(ownerConceptId)?.[1];
+    if (wikiRoot && /^(raw|pages)\//.test(stripped))
+        return `${wikiRoot}${stripped}`;
+    return stripped;
+}

package/dist/indexer/passes/metadata.js

@@ -743,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.

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

@@ -138,6 +138,7 @@ export function indexDocumentToStashEntry(doc) {
         entry.wikiRole = dj.wikiRole;
     assignStringList(entry, "sources", dj.sources);
     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/walk/walker.js

@@ -169,10 +169,9 @@ function isInsideGitRepo(dir) {
 /**
  * Recursively collect every `.md` file under `root`.
  *
- * Shared by graph-extraction and memory-inference so the walk logic lives in
- * exactly one place. Mirrors the `complete` tracking of the other walkers in
- * this file: a directory that cannot be read makes the result incomplete
- * instead of silently looking like a clean, empty scan.
+ * Used by memory-inference. Mirrors the `complete` tracking of the other
+ * walkers in this file: a directory that cannot be read makes the result
+ * incomplete instead of silently looking like a clean, empty scan.
  */
 export function walkMarkdownFiles(root) {
     const files = [];

package/dist/llm/client.js

@@ -101,10 +101,9 @@ function retryBackoffMs() {
  * narrating about a document) does not get misclassified as a provider
  * context-limit error (#496).
  *
- * Canonical home: `graph-extract.ts` re-exports this so the index-pass
- * graph extractor and the retry classifier (`isRetryable`) share one
- * definition — retrying a context overflow cannot shrink the input, so it
- * must never be retried.
+ * Canonical home: `structured-call.ts`'s failure classifier and the retry
+ * classifier (`isRetryable`) here share one definition — retrying a context
+ * overflow cannot shrink the input, so it must never be retried.
  */
 export function isContextSizeError(message) {
     const lower = message.toLowerCase();
@@ -120,13 +119,12 @@ export function isContextSizeError(message) {
 /**
  * Codes describing a failure to reach or get a usable response from the
  * provider transport itself, as opposed to a malformed-but-received response
- * (`parse_error`) or a request-shape rejection (`rate_limited`). Shared by
- * {@link isRetryable} (which additionally requires evidence the failure is
- * transient) and the batch graph-extraction storm guard in `graph-extract.ts`
- * (which treats any of these as "the provider is down, stop retrying
- * per-asset") so the two classifications cannot drift apart.
+ * (`parse_error`) or a request-shape rejection (`rate_limited`). Used by
+ * {@link isRetryable}, which additionally requires evidence the failure is
+ * transient. Not exported — its one external caller (batched LLM
+ * entity-graph extraction) was retired in 0.9.17-alpha.9.
  */
-export function isTransportFailure(err) {
+function isTransportFailure(err) {
     return err.code === "provider_error" || err.code === "network_error" || err.code === "provider_html_error";
 }
 /**

package/dist/llm/embedders/remote.js

@@ -187,8 +187,7 @@ export function isContextExceededResponse(status, body) {
  * Resolve the effective in-flight request window for `RemoteEmbedder.embedBatch`.
  * Default (unset `embedding.concurrency`): 1 for a loopback endpoint, 2 for a
  * remote one, via the shared `defaultConcurrencyForEndpoint`
- * (`src/core/loopback.ts`), the same lowest-common-denominator rule
- * `getDefaultLlmConcurrency` (`src/indexer/indexer.ts`) uses.
+ * (`src/core/loopback.ts`).
  *
  * `embedding.concurrency` (#954) overrides this default in
  * either direction, bounded 1-16 at the config schema — added after field

package/dist/llm/feature-gate.js

@@ -7,8 +7,6 @@
  */
 const FEATURE_LOCATION = {
     memory_inference: (cfg) => cfg.index?.memory?.enabled ?? true,
-    graph_extraction: (cfg) => cfg.index?.graph?.enabled ?? true,
-    metadata_enhance: (cfg) => cfg.index?.metadataEnhance?.enabled ?? false,
     // #951: a real implementation of the dead `curate_rerank` key removed in
     // 0.8.0. Off by default — it requires a `search.curateRerank.endpoint` a
     // caller must explicitly configure.
@@ -82,9 +80,6 @@ export function isProcessEnabled(section, processName, config) {
         if (processName === "memory_inference" || processName === "memoryInference") {
             return isLlmFeatureEnabled(config, "memory_inference");
         }
-        if (processName === "graph_extraction" || processName === "graphExtraction") {
-            return isLlmFeatureEnabled(config, "graph_extraction");
-        }
     }
     return false;
 }

package/dist/output/shapes/helpers.js

@@ -56,11 +56,25 @@ export function shapeProposalProducerOutput(result, detail) {
 }
 export function shapeProposalEntry(entry, detail) {
     if (detail === "brief") {
-        return pickFields(entry, ["id", "ref", "status", "source", "createdAt"]);
+        // `proposal list`'s default detail level IS "brief" (no `--detail` flag
+        // given projects here, not "normal") — `retirement` itself is not
+        // projected until "normal", so a flagged retire proposal's risk would
+        // otherwise be invisible by default. A minimal boolean marker, not the
+        // full risk object, keeps brief's shape small while still letting a
+        // reviewer see it without an extra flag.
+        const retirement = entry.retirement;
+        return {
+            ...pickFields(entry, ["id", "ref", "status", "source", "createdAt"]),
+            ...(retirement?.continuityRisk ? { continuityRisk: true } : {}),
+        };
     }
     if (detail === "normal") {
         // `confidence` and `gateDecision` (#577) explain why a proposal is pending,
         // so they are projected at `normal` for `akm proposal list/show` when present.
+        // `retirement` (alpha.9) is the same kind of field for a consolidate
+        // `retire` proposal: without it, "list/show" carries no reason a reviewer
+        // could act on (its `payload.content` is empty by design — a retire
+        // proposal deletes, it does not write).
         return pickFields(entry, [
             "id",
             "ref",
@@ -72,6 +86,7 @@ export function shapeProposalEntry(entry, detail) {
             "confidence",
             "gateDecision",
             "review",
+            "retirement",
         ]);
     }
     // full: project everything including the payload.
@@ -87,6 +102,10 @@ export function shapeProposalEntry(entry, detail) {
         "gateDecision",
         "payload",
         "review",
+        "retirement",
+        "retiredArchive",
+        "promotionSource",
+        "promotionSourceHash",
     ]);
 }
 export function shapeProposalListOutput(result, detail) {
@@ -357,7 +376,7 @@ export function shapeShowOutput(result, detail, shape = "human") {
             "workflowParameters",
             "steps",
             "keys",
-            "related",
+            "links",
             ...FRAGMENT_PROVENANCE_FIELDS,
             ...FRAGMENT_CONTEXT_FIELDS,
         ]);
@@ -381,7 +400,7 @@ export function shapeShowOutput(result, detail, shape = "human") {
             "run",
             "origin",
             "keys",
-            "related",
+            "links",
             ...FRAGMENT_PROVENANCE_FIELDS,
             ...FRAGMENT_CONTEXT_FIELDS,
         ]);
@@ -410,7 +429,7 @@ export function shapeShowOutput(result, detail, shape = "human") {
         "cwd",
         "activeRun",
         "keys",
-        "related",
+        "links",
         ...FRAGMENT_PROVENANCE_FIELDS,
         ...FRAGMENT_CONTEXT_FIELDS,
         // ref, path, and editable are always projected — at every --detail level,

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

@@ -407,14 +407,6 @@ export function formatIndexPlain(r) {
         for (const message of warnings)
             out += `\n  - ${String(message)}`;
     }
-    const notices = Array.isArray(indexResult.notices) ? indexResult.notices : [];
-    for (const notice of notices) {
-        const severity = notice.severity === "info" ? "info" : "warning";
-        const field = typeof notice.field === "string" ? ` field=${notice.field}` : "";
-        out +=
-            `\n  notice[${severity}] ${notice.code} adapter=${notice.adapter}${field}` +
-                (notice.message ? `: ${notice.message}` : "");
-    }
     const verification = indexResult.verification;
     if (verification?.ok === false && verification.message) {
         out += `\nVerification: ${String(verification.message)}`;

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

@@ -100,7 +100,16 @@ export function formatProposalListPlain(r) {
         // #577: surface the gate verdict inline so the queue explains itself.
         const gate = formatGateDecisionSummary(p.gateDecision);
         const gateSuffix = gate ? `  ${gate}` : "";
-        lines.push(`${id}  [${status}] ${ref}  source=${source}  ${created}${gateSuffix}`);
+        // A retire proposal's continuityRisk excludes it from bulk accept —
+        // visible in the default list, not just `proposal show`, since the owner
+        // reviews the backlog list-first. `list`'s default (brief) shape
+        // projects a `continuityRisk: true` marker instead of the full
+        // `retirement` object (only present from `--detail normal` up), so both
+        // shapes are checked here.
+        const retirement = p.retirement;
+        const flagged = p.continuityRisk === true || Boolean(retirement?.continuityRisk);
+        const continuitySuffix = flagged ? "  ⚠ continuity-risk" : "";
+        lines.push(`${id}  [${status}] ${ref}  source=${source}  ${created}${gateSuffix}${continuitySuffix}`);
     }
     return lines.join("\n").trimEnd();
 }
@@ -141,6 +150,43 @@ export function formatProposalShowPlain(r) {
         if (review.decidedAt)
             lines.push(`review.decidedAt: ${String(review.decidedAt)}`);
     }
+    // alpha.9: a consolidate retire proposal writes no content (`payload.content`
+    // is empty by design) — this is the reason a reviewer needs instead. `diff`
+    // shows the body being retired.
+    const retirement = p.retirement;
+    if (retirement) {
+        lines.push(`retire: ${String(retirement.retiredRef)} -> ${String(retirement.successorRef)}`);
+        lines.push(`retire.label: ${String(retirement.judgeLabel)} (cosine=${String(retirement.cosine)})`);
+        lines.push(`retire.reason: ${String(retirement.judgeReason)}`);
+        // Item 1 (continuity check): flagged, but still minted — never swept by a
+        // bulk accept, only acceptable by id, so a reviewer must see it here.
+        const continuityRisk = retirement.continuityRisk;
+        if (continuityRisk) {
+            const failingQueries = typeof continuityRisk.failingQueries === "number" ? continuityRisk.failingQueries : 0;
+            const unverifiedQueries = typeof continuityRisk.unverifiedQueries === "number" ? continuityRisk.unverifiedQueries : 0;
+            const summary = [];
+            if (failingQueries > 0) {
+                summary.push(`${failingQueries} of the retired asset's own quer${failingQueries === 1 ? "y" : "ies"} would not have found the successor top 10`);
+            }
+            // S2: a query the search call never ran, or that fell back to
+            // keyword-only ranking, is never silently trusted OR silently
+            // dropped — it excludes the proposal from bulk accept on its own.
+            if (unverifiedQueries > 0) {
+                summary.push(`${unverifiedQueries} quer${unverifiedQueries === 1 ? "y" : "ies"} unverified (search failed or used the keyword-only fallback)`);
+            }
+            lines.push(`retire.continuityRisk: ${summary.join("; ")} — excluded from bulk accept`);
+            // N3 / S4: the actual failing query text, not just the count — a
+            // reviewer deciding whether to accept by id needs to see what would
+            // stop resolving, not just how many queries.
+            const ranks = Array.isArray(continuityRisk.ranks) ? continuityRisk.ranks : [];
+            for (const rank of ranks) {
+                const successorRank = rank.successorRank === null || rank.successorRank === undefined
+                    ? "absent from top 10"
+                    : `#${String(rank.successorRank)}`;
+                lines.push(`  - "${String(rank.query)}": retired #${String(rank.retiredRank)}, successor ${successorRank}`);
+            }
+        }
+    }
     const validation = r.validation;
     if (validation) {
         const findings = Array.isArray(validation.findings) ? validation.findings : [];

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

@@ -54,17 +54,20 @@ export function formatShowPlain(r, detail) {
         if (r.schemaVersion !== undefined)
             lines.push(`schemaVersion: ${String(r.schemaVersion)}`);
     }
-    const related = typeof r.related === "object" && r.related !== null ? r.related : undefined;
-    const relatedHits = related && Array.isArray(related.hits) ? related.hits : [];
-    if (related) {
+    const links = typeof r.links === "object" && r.links !== null ? r.links : undefined;
+    if (links) {
         lines.push("");
-        lines.push(`related: ${String(related.total ?? relatedHits.length)}`);
-        for (const hit of relatedHits) {
-            lines.push(`  - ${String(hit.type ?? "?")}: ${formatRelatedLabel(hit)}`);
-            const shared = Array.isArray(hit.sharedEntities) ? hit.sharedEntities.map(String) : [];
-            if (shared.length > 0)
-                lines.push(`    shared: ${shared.join(", ")}`);
-            lines.push(`    relationCount: ${String(hit.relationCount ?? 0)}`);
+        lines.push("links:");
+        for (const part of ["outgoing", "incoming", "unresolved"]) {
+            const groups = links[part];
+            if (typeof groups !== "object" || groups === null)
+                continue;
+            lines.push(`  ${part}:`);
+            for (const [kind, group] of Object.entries(groups)) {
+                const refs = Array.isArray(group.refs) ? group.refs.map(String) : [];
+                const more = (group.total ?? refs.length) > refs.length ? ` (+${(group.total ?? 0) - refs.length} more)` : "";
+                lines.push(`    ${kind}: ${refs.join(", ")}${more}`);
+            }
         }
     }
     const payloads = [r.content, r.template, r.prompt].filter((value) => value != null).map(String);
@@ -98,10 +101,3 @@ export function formatShowPlain(r, detail) {
     appendShowDirectives(lines, r);
     return lines.length > 0 ? lines.join("\n") : null;
 }
-function formatRelatedLabel(hit) {
-    const ref = typeof hit.ref === "string" ? hit.ref : undefined;
-    if (ref)
-        return ref;
-    const pathValue = typeof hit.path === "string" ? hit.path : "?";
-    return pathValue.split("/").pop() ?? pathValue;
-}