akm-cli 0.9.17-alpha.6 → 0.9.17-alpha.8

package/dist/core/improve-result.js

@@ -306,6 +306,8 @@ function validateImprovePlan(value, dryRun, plannedRefNames) {
         fail("plan.limits.totalCeiling must equal plan.limits.effective + plan.limits.additiveReplayAllowance");
     }
     const gateNames = new Set(["profile", "cleanup", "validation", "signal", "disk", "limit"]);
+    // Plans stored before 0.9.17-alpha.7 (#986) have no retrieval gate.
+    const optionalGateNames = new Set(["retrieval"]);
     if (!Array.isArray(value.gates))
         fail("plan.gates must be an array");
     const gateRemovedByName = new Map();
@@ -313,8 +315,9 @@ function validateImprovePlan(value, dryRun, plannedRefNames) {
         if (!isRecord(gate))
             fail("plan.gates entries must be objects");
         requireExactFields(gate, new Set(["name", "removed", "reason"]));
-        if (typeof gate.name !== "string" || !gateNames.has(gate.name))
+        if (typeof gate.name !== "string" || !(gateNames.has(gate.name) || optionalGateNames.has(gate.name))) {
             fail("plan.gates.name is invalid");
+        }
         requireCount(gate, "removed", "plan.gates entry");
         if (typeof gate.reason !== "string")
             fail("plan.gates.reason must be a string");

package/dist/core/non-task-input.js

@@ -0,0 +1,20 @@
+// 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/.
+/** The line of `src/assets/stash-skeleton/README.md` that reaches curate verbatim as a query. */
+const STASH_README_LINE = "This is an **AKM stash** — a structured knowledge repository that stores reusable";
+/**
+ * What the (trimmed) curate input is when it is not a task, else undefined.
+ * Harness and tool envelopes (`<task-notification>…`, `<system-reminder>…`,
+ * `<cross-session-message …>…`) start with a tag and close one, and the stash
+ * README line arrives verbatim; on the retrieval suite neither shape occurs in
+ * a real query. Length is not a signal: prompts over 2,000 characters found
+ * relevant assets at about the rate of shorter long prompts.
+ */
+export function nonTaskInput(query) {
+    if (query.startsWith("<") && query.includes("</"))
+        return "a harness or tool envelope";
+    if (query === STASH_README_LINE)
+        return "the akm stash README boilerplate";
+    return undefined;
+}

package/dist/core/paths.js

@@ -249,10 +249,6 @@ export function getIndexRebuildLockPath() {
 export function getStateDbPathInDataDir() {
     return path.join(getDataDir(), "state.db");
 }
-/** Content-addressed scheduler runtime descriptors. */
-export function getTaskContextDir(env = process.env) {
-    return path.join(getDataDir(env), "tasks", "context");
-}
 /** Path to the akm.lock file in $DATA. */
 export function getLockfilePath() {
     return path.join(getDataDir(), "akm.lock");

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

@@ -242,38 +242,6 @@ export function deleteStoredGraph(db, stashPath) {
         db.prepare("DELETE FROM graph_meta WHERE stash_root = ?").run(stashPath);
     })();
 }
-/**
- * Scoped loader — graph_files rows without entities/relations. Used for
- * orphan detection and entity overview commands.
- */
-export function loadGraphFilesOnly(stashPath, db) {
-    try {
-        return withReadableGraphDb(db, (readDb) => {
-            const rows = readDb
-                .prepare(`SELECT file_path, file_type, body_hash, confidence, status, reason
-              FROM graph_files
-              WHERE stash_root = ?
-              ORDER BY file_order`)
-                .all(stashPath);
-            return rows.map((row) => ({
-                path: row.file_path,
-                type: row.file_type,
-                bodyHash: row.body_hash,
-                ...(typeof row.confidence === "number" ? { confidence: row.confidence } : {}),
-                ...(row.status ? { status: row.status } : {}),
-                ...(row.reason ? { reason: row.reason } : {}),
-            }));
-        });
-    }
-    catch (err) {
-        // Never mask the bun-test isolation guard as "no stored graph files",
-        // and never mask an index we are not allowed to read as one with no
-        // graph in it (#791) — `GRAPH_DB_MISSING` above is the only "absent".
-        rethrowIfTestIsolationError(err);
-        rethrowIfDataDirUnreadable(err);
-        return [];
-    }
-}
 export function loadStoredGraphMeta(stashPath, db) {
     try {
         return withReadableGraphDb(db, (readDb) => {

package/dist/indexer/graph/graph-extraction.js

@@ -7,7 +7,7 @@
  * Walks the primary stash for `memory:` and `knowledge:` assets, asks the
  * configured LLM to extract entities and relations from each one, and
  * persists the result to stash-local SQLite graph tables keyed by stash root.
- * The artifact backs `akm show`'s `related` list and curate's support refs
+ * The artifact backs `akm show`'s `related` list
  * (`src/indexer/graph/graph-related.ts`); it plays no part in search ranking.
  *
  * Disabling — three preconditions must ALL hold for the pass to run:
@@ -344,6 +344,8 @@ function extractionRecord(candidate, bodyHash, shape) {
  * Run the planned extractions in chunks of `batchSize`: cache hits are taken
  * as-is, and each chunk's model plans go to the provider in one
  * `extractGraphFromBodies` call (a one-body call is the per-asset path).
+ * Up to the runner's concurrency of chunks run at once, and each makes one
+ * call at a time, so that is also the most calls the run has in flight.
  */
 async function extractGraphBatches(args) {
     const { plans, batchSize, signal, db, cacheVariant, telemetry, llmRunner, featureConfig, onFallback, abortState, batchState, runtimeTelemetry, onNotices, reportProgress, maxChunksPerAsset, } = args;

package/dist/indexer/indexer.js

@@ -35,7 +35,7 @@ import { generateEmbeddingsForDb } from "./materialize-embeddings.js";
 import { canUseIncrementalSkip, computeDirFingerprint, getCachedDirState, getDirIndexState, inferZeroRowReason, } from "./passes/dir-staleness.js";
 import { isEnrichmentComplete, isWorkflowSkipWarning, withFileSize, } from "./passes/metadata.js";
 import { drainDirDocuments } from "./scan/drain-dir.js";
-import { purgeOldUsageEvents } from "./usage/usage-events.js";
+import { purgeOldUsageEvents, USAGE_EVENT_RETENTION_DAYS } from "./usage/usage-events.js";
 import { walkStashFlatWithStatus } from "./walk/walker.js";
 function collectLoweringNotices(target, notices) {
     const keys = new Set(target.map((notice) => JSON.stringify(notice)));
@@ -1624,8 +1624,6 @@ export async function lookup(ref) {
     return lookupBundleRef({ bundle: ref.origin, conceptId: conceptIdFromTypeName(ref.type, ref.name) });
 }
 // ── Utility score recomputation ──────────────────────────────────────────────
-/** Retention window for usage events: events older than this are purged. */
-const USAGE_EVENT_RETENTION_DAYS = 90;
 /**
  * Recompute utility scores for all entries based on usage_events data.
  *

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/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/usage/usage-events.js

@@ -91,6 +91,40 @@ export function countUsageEventsByType(db, eventType) {
     return db.prepare("SELECT COUNT(*) AS cnt FROM usage_events WHERE event_type = ?").get(eventType)
         .cnt;
 }
+/**
+ * Durable refs a user-attributed `search`, `curate` or `show` returned, or a
+ * user `feedback` named, at or after `sinceIso`. Machine traffic (`improve`,
+ * `task`, `audit`, `unknown`) is not demand, as in {@link countFeedbackSignals}.
+ */
+export function listUsedEntryRefs(db, sinceIso) {
+    const rows = db
+        .prepare(`SELECT DISTINCT entry_ref FROM usage_events
+       WHERE event_type IN ('search', 'curate', 'show', 'feedback')
+         AND source = 'user'
+         AND entry_ref IS NOT NULL
+         AND julianday(created_at) >= julianday(?)`)
+        .all(sinceIso);
+    return rows.map((row) => row.entry_ref);
+}
+/**
+ * The distinct query texts of user `search` and `curate` events that returned
+ * `conceptId` (any bundle prefix), most recent first.
+ */
+export function listRetrievalQueries(db, conceptId) {
+    const rows = db
+        .prepare(`SELECT query, MAX(created_at) AS last_at FROM usage_events
+       WHERE event_type IN ('search', 'curate')
+         AND source = 'user'
+         AND query IS NOT NULL AND trim(query) != ''
+         AND instr(entry_ref, '//') > 0
+         AND substr(entry_ref, instr(entry_ref, '//') + 2) = ?
+       GROUP BY query
+       ORDER BY last_at DESC`)
+        .all(conceptId);
+    return rows.map((row) => row.query);
+}
+/** Usage events older than this many days are purged on every `akm index`. */
+export const USAGE_EVENT_RETENTION_DAYS = 90;
 /**
  * Delete usage events older than the given number of days.
  */

package/dist/llm/graph-extract.js

@@ -185,30 +185,6 @@ function bumpTelemetry(telemetry, key, amount = 1) {
         return;
     telemetry[key] = (telemetry[key] ?? 0) + amount;
 }
-/**
- * `Promise.all(items.map(fn))` with at most `limit` calls in flight, so the
- * per-asset calls of one batch never outnumber the chunk pool's concurrency
- * (GR-D14). The first rejection rejects the map and stops further calls.
- */
-async function mapWithConcurrency(items, limit, fn) {
-    const results = new Array(items.length);
-    let next = 0;
-    let failed = false;
-    const worker = async () => {
-        while (!failed && next < items.length) {
-            const index = next++;
-            try {
-                results[index] = await fn(items[index]);
-            }
-            catch (error) {
-                failed = true;
-                throw error;
-            }
-        }
-    };
-    await Promise.all(Array.from({ length: Math.min(Math.max(1, limit), items.length) }, worker));
-    return results;
-}
 /** Count what the parser dropped from one parsed extraction (single-asset or batch item). */
 function bumpFilterTelemetry(telemetry, extraction) {
     bumpTelemetry(telemetry, "filteredGenericEntities", extraction.filteredGenericEntities ?? 0);
@@ -260,6 +236,7 @@ function mergeGraphExtractions(extractions) {
     let filteredGenericEntities = 0;
     let filteredInvalidRelations = 0;
     let filteredLowConfidenceRelations = 0;
+    let anyChunkFailed = false;
     let firstFailureReason;
     for (const extraction of extractions) {
         truncationCount += extraction.truncationCount ?? 0;
@@ -267,8 +244,10 @@ function mergeGraphExtractions(extractions) {
         filteredGenericEntities += extraction.filteredGenericEntities ?? 0;
         filteredInvalidRelations += extraction.filteredInvalidRelations ?? 0;
         filteredLowConfidenceRelations += extraction.filteredLowConfidenceRelations ?? 0;
-        if (extraction.status === "failed" && !firstFailureReason)
-            firstFailureReason = extraction.reason;
+        if (extraction.status === "failed") {
+            anyChunkFailed = true;
+            firstFailureReason ??= extraction.reason;
+        }
         const nextConfidence = parseConfidence(extraction.confidence);
         if (nextConfidence !== undefined)
             confidence = confidence === undefined ? nextConfidence : Math.max(confidence, nextConfidence);
@@ -329,8 +308,12 @@ function mergeGraphExtractions(extractions) {
         const chunkCount = relationChunkCounts.get(key) ?? 1;
         relation.confidence = blendConsistency(relation.confidence, chunkCount);
     }
-    const status = entities.length > 0 ? "extracted" : firstFailureReason ? "failed" : "empty";
-    const reason = status === "extracted" ? "none" : (firstFailureReason ?? "no_graph_content");
+    // One failed chunk fails the body, whatever the others found: a failed
+    // extraction is never cached, so the next run extracts the body again
+    // (every chunk: partial failures are rare outside provider outages, which
+    // the run's failure-rate abort stops). The entities found are kept.
+    const status = anyChunkFailed ? "failed" : entities.length > 0 ? "extracted" : "empty";
+    const reason = status === "extracted" ? "none" : status === "failed" ? (firstFailureReason ?? "llm_error") : "no_graph_content";
     const mergedConfidence = confidence !== undefined ? blendConsistency(confidence, totalChunks) : totalChunks > 1 ? 1 : undefined;
     return {
         entities,
@@ -606,11 +589,21 @@ export async function extractGraphFromBodies(llmRunner, bodies, signal, akmConfi
         const result = await extractGraphFromBody(llmRunner, bodies[0] ?? "", signal, akmConfig, onFallback, options);
         return [result];
     }
-    const concurrency = llmRunner.connection.concurrency ?? 1;
+    // A batch makes its per-asset calls one at a time: the caller's pool runs
+    // batches side by side and is the run's only concurrency, so the calls in
+    // flight never exceed it (not the pool's width squared).
     const extractOne = (body) => extractGraphFromBody(llmRunner, body, signal, akmConfig, onFallback, options);
+    const extractEach = async (indices, into) => {
+        for (const index of indices)
+            into[index] = await extractOne(bodies[index] ?? "");
+    };
     // With batching disabled every body takes the single-asset path, once.
-    if (batchState?.batchingDisabled)
-        return mapWithConcurrency(bodies, concurrency, extractOne);
+    if (batchState?.batchingDisabled) {
+        const results = [];
+        for (const body of bodies)
+            results.push(await extractOne(body));
+        return results;
+    }
     // Filter out bodies that are empty so we don't waste tokens, but keep
     // index correspondence by tracking which indices were non-empty.
     const results = bodies.map(empty);
@@ -629,9 +622,7 @@ export async function extractGraphFromBodies(llmRunner, bodies, signal, akmConfi
             }
         }
     }
-    await mapWithConcurrency(oversizedIndices, concurrency, async (index) => {
-        results[index] = await extractOne(bodies[index] ?? "");
-    });
+    await extractEach(oversizedIndices, results);
     if (nonEmptyBodies.length === 0)
         return results;
     const systemPrompt = buildBatchSystemPrompt();
@@ -780,9 +771,7 @@ export async function extractGraphFromBodies(llmRunner, bodies, signal, akmConfi
             warn(`graph extraction (batch): response had ${batchResult.length} items for ${nonEmptyBodies.length} assets; ` +
                 `falling back to individual calls for ${fallbackIndices.length} missing asset(s).`);
         }
-        await mapWithConcurrency(fallbackIndices, concurrency, async (origIdx) => {
-            results[origIdx] = await extractOne(bodies[origIdx] ?? "");
-        });
+        await extractEach(fallbackIndices, results);
     }
     else if (batchContextError) {
         warn(`graph extraction (batch): skipped ${nonEmptyBodies.length} asset(s) due to context size error; ` +

package/dist/output/shapes/helpers.js

@@ -358,6 +358,7 @@ export function shapeShowOutput(result, detail, shape = "human") {
             "steps",
             "keys",
             "related",
+            "links",
             ...FRAGMENT_PROVENANCE_FIELDS,
             ...FRAGMENT_CONTEXT_FIELDS,
         ]);
@@ -382,6 +383,7 @@ export function shapeShowOutput(result, detail, shape = "human") {
             "origin",
             "keys",
             "related",
+            "links",
             ...FRAGMENT_PROVENANCE_FIELDS,
             ...FRAGMENT_CONTEXT_FIELDS,
         ]);
@@ -411,6 +413,7 @@ export function shapeShowOutput(result, detail, shape = "human") {
         "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/show-format.js

@@ -67,6 +67,22 @@ export function formatShowPlain(r, detail) {
             lines.push(`    relationCount: ${String(hit.relationCount ?? 0)}`);
         }
     }
+    const links = typeof r.links === "object" && r.links !== null ? r.links : undefined;
+    if (links) {
+        lines.push("");
+        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);
     if (Array.isArray(r.steps) && r.steps.length > 0) {
         if (lines.length > 0)