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

package/CHANGELOG.md

@@ -6,6 +6,145 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.17-alpha.8] - 2026-09-28
+
+`akm index` now records the links a bundle already declares (`xrefs`,
+`supersededBy`, a `.derived` memory's parent, wiki sources, page links, and
+workflow and task targets) as typed links, with no model. `akm show` lists
+them, and curate's support refs come from them instead of the LLM entity
+graph. The index moves to layout 26 in place on its first writable open;
+0.9.17-alpha.4 through alpha.7 cannot open it. `index.graph.enabled: false`
+now stops graph extraction in `akm improve`, and a partly failed extraction is
+retried. `akm migrate` converts a v2 or v3 task file to v4 in one pass, and
+the launchers no longer lose a signal that arrives before their child starts.
+
+### Added
+
+- **Declared links (#935).** The relations a bundle already declares are now
+  stored as typed links: `xrefs:` (`xref`), `supersededBy:`
+  (`superseded_by`), `contradictedBy:` (`contradicted_by`),
+  `currentBeliefRefs:` (`belief_peer`), a `.derived` memory's parent
+  (`derived_from`), wiki `sources:` that name an asset (`cites`), the page
+  links an llm-wiki or OKF bundle resolves (`links_to`), and a workflow step's
+  or a task's target (`uses`). `akm index` reads them from what it already
+  parses, with no model, so an install without an LLM engine gets them. They
+  live in their own table (`asset_links`), apart from the LLM entity graph:
+  each link belongs to the entry that declares it and is written, replaced
+  and deleted with it, including on incremental and write-path (`akm
+  remember`) indexing. A target resolves when it is indexed, not when its
+  citer was, so a note that cites something added later links to it without
+  being reindexed. Retired spellings convert in memory (`memory:<name>`,
+  `wiki:<wiki>/<page>`, a `.md` suffix), and, as lint already allows (#882),
+  a memory whose own file is gone resolves to its `.derived` child.
+  `akm show` lists an asset's links grouped by kind: `outgoing`, `incoming`
+  and the `unresolved` tokens it names, at most 10 per kind with a `total`.
+  `akm info` reports links per kind with how many are unresolved. Links do
+  not change search ranking, and `related` is unchanged: on the retrieval
+  suite, against 0.9.17-alpha.7 on the same index with two runs per arm,
+  search nDCG@10 moved +0.002 [−0.005, +0.009] (a rerun of alpha.7 alone
+  moved +0.006) and curate P@5 +0.000 [−0.001, +0.001].
+  On the retrieval snapshot of the maintainer's 21 bundles (23,979 entries)
+  there are 14,917 links: 7,393 `contradicted_by`, 4,401 `xref`, 2,577
+  `derived_from`, 540 `cites` and 6 `superseded_by`. 1,801 are unresolved;
+  1,744 of those are `.derived` memories whose parent memory no longer
+  exists. (`src/indexer/links/declared-links.ts`,
+  `src/storage/repositories/index-links-repository.ts`,
+  `src/commands/read/show.ts`, `src/commands/sources/info.ts`)
+
+### Changed
+
+- **`akm migrate` converts a v2 or v3 task file straight to v4 in one pass.**
+  The chain that read every file as v2, converted it to an intermediate v3
+  shape, then converted that to v4 (`src/tasks/source/task-to-v3.ts` ->
+  `task-to-v4.ts`, composed by `scripts/akm-migrate/migrate/task-files.ts`)
+  is now one planner: `task-to-v4.ts` reads a file once and, for v2, builds
+  the v3-shape record in memory — never written to disk or reported as its
+  own outcome — before hoisting it to v4 through the same code path a real
+  v3 file goes through. `akm migrate status`/`apply` output shapes, and
+  every blocked/changed reason code, are unchanged, checked fixture by
+  fixture against the prior two-hop chain's actual output (one exception:
+  a v3 document that fails only the typed pre-check's own "exactly one
+  scheduling source" rule — unreachable through the real chain, which
+  always ran that same pre-check first — now reports `invalid-v3-task`
+  instead of the raw hoist stage's own `ambiguous-scheduling-source`,
+  matching what `akm migrate apply` already returned end to end). The
+  `already-v3` and `pending-v2-to-v3-migration` intermediate states are
+  gone with the generation split that produced them.
+  `src/tasks/source/task-to-v3.ts` (500 lines) is deleted; its logic moved
+  into `task-to-v4.ts`, which also drops the duplicate raw-YAML reader and
+  outcome-base helpers the two files each carried their own copy of.
+  (`src/tasks/source/task-to-v4.ts`, `scripts/akm-migrate/migrate/task-files.ts`)
+- **Curate's support refs come from declared links.** Each curated item's
+  support refs (at most two) are now assets its declared links name: what
+  it links to, then what links to it, in the order `akm show` lists them,
+  skipping assets curate already selected. They no longer come from the LLM
+  entity graph's `related` list. On the retrieval snapshot, `related` offered
+  support refs for 47 of 867 curate items (5.4%) and declared links for 257
+  (29.6%). The retrieval judge graded 157 of those items, asking whether each
+  support ref is worth opening next: 56% of declared support refs were useful
+  against 68% of `related`'s, so curate attaches about 24 useful support refs
+  per 100 items instead of 7. Curate's items are unchanged.
+  (`src/commands/read/curate.ts`)
+- **Index layout 26.** The first writable open of an older index derives
+  every entry's links from its stored `document_json` in place, reading no
+  file: on the 23,979-entry snapshot index that takes 0.8 s and adds 3.5 MB.
+  Earlier layouts never stored a workflow's or a task's targets, so only the
+  directories holding workflows and tasks re-read on the next `akm index`.
+  The open leaves `index_meta.vacuumPending` like every layout migration.
+  0.9.17-alpha.4 through alpha.7 refuse an index at layout 26
+  (`INDEX_SCHEMA_INCOMPATIBLE`, naming the upgrade), for writing as well as
+  reading, so going back to one of them needs a new index: move `index.db`
+  aside and run `akm index` under that release (the LLM graph and enrichment
+  cache it held are not rebuilt by `akm index`).
+  (`src/storage/repositories/index-schema.ts`,
+  `src/storage/repositories/index-entry-schema.ts`)
+
+### Fixed
+
+- **`index.graph.enabled: false` stops graph extraction in `akm improve`.**
+  The switch was read only when improve had no strategy plan, which is never
+  the case in a real run, so the nightly and weekly graph tasks kept
+  extracting with it set. Improve now skips its graph extraction stage
+  whenever `index.graph.enabled` is `false`, whatever the strategy enables.
+  This also makes the graph ablation harness's "graph off" arm, which sets
+  exactly this key, turn extraction off. Improve still does not read
+  `index.defaults` when it picks the engine for graph extraction.
+  (`src/commands/improve/loop-stages.ts`)
+- **Graph extraction never has more calls in flight than the run's
+  concurrency.** Batches run side by side up to the runner's concurrency, and
+  each batch also sent its per-file calls (long bodies, a non-array response)
+  up to that limit at once, so at a concurrency of 2 four calls could be in
+  flight. A batch now makes its per-file calls one at a time. At the default
+  concurrency of 1 nothing changes. (`src/llm/graph-extract.ts`)
+- **A long document whose extraction partly failed is extracted again.** A
+  body over 1,600 characters is extracted in chunks. When some chunks failed
+  (a timeout, an error, an empty response) and others found entities, the
+  file was recorded and cached as extracted, so the failed chunks were never
+  retried. Such a file is now recorded as failed and not cached, and the next
+  run extracts it again, every chunk: partial failures are rare outside
+  provider outages, and keeping per-chunk results to skip the chunks that
+  succeeded would need a second cache. Until then the entities the other
+  chunks found are stored when the file had no graph rows yet; a file with
+  rows keeps them. (`src/llm/graph-extract.ts`)
+- **`scripts/node-runtime/akm` could die from a raw signal instead of
+  forwarding it to its child.** The launcher registered its
+  SIGTERM/SIGINT/SIGHUP forwarding listeners only after spawning the child;
+  under load, a signal could arrive in that window and fall through to the
+  runtime's default (process-terminating) disposition, killing the launcher
+  before the child ever saw it. The listeners now go up before anything else
+  runs, with a small queue for a signal that arrives before the child exists.
+- **`scripts/node-runtime/akm-migrate` carried the same pre-spawn signal
+  race** as `scripts/node-runtime/akm` above, for the same reason (listeners
+  registered only after `spawn()`), with no test covering it. Fixed the same
+  way, and added `tests/integration/akm-migrate-signal-forwarding.test.ts`
+  (modelled on `launcher-signal-forwarding.test.ts`) for its forwarding.
+- **The launcher signal tests failed intermittently because of their own
+  fixture.** The fake child wrote its ready file before it registered its
+  signal handler, so a forwarded signal could reach it in between and kill it,
+  and the launcher then reported that signal. Each fixture now registers its
+  handler first. The launcher's pre-spawn window above could not cause this:
+  the tests signal only after the child is running.
+
 ## [0.9.17-alpha.7] - 2026-09-28
 
 A scheduled task is now just a command and a schedule. Each native row

package/dist/akm

@@ -6,6 +6,48 @@
 import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
+// #956 round 3: install the signal-forwarding scaffolding before ANYTHING
+// else in this process — env var setup, the bun-version probe, spawning the
+// child — gets a chance to run. The three `process.once` listeners used to
+// go up only after spawn() (below) returned; a scheduler preemption right
+// after that syscall was enough for a signal to arrive with no listener yet,
+// and the runtime's default (process-terminating) disposition killed the
+// launcher outright, never reaching the child at all. `child` starts
+// unset: a signal that arrives before it exists is queued and flushed the
+// moment it does; if this process ends up never spawning one (the
+// direct-import branch below), the queued signal is re-raised against
+// ourselves once we hand default disposition back, so it behaves exactly
+// like the runtime's own default rather than being silently swallowed.
+let child;
+let childExited = false;
+const pendingSignals = [];
+const forwardHandlers = new Map();
+const forwardSignal = (signal) => {
+  if (childExited) return;
+  if (!child) {
+    pendingSignals.push(signal);
+    return;
+  }
+  try {
+    child.kill(signal);
+  } catch {
+    // Child exited in the race between the check above and here.
+  }
+};
+// `.once`, not `.on`: Node/Bun suppress a signal's default
+// (process-terminating) disposition for as long as ANY listener stays
+// registered for it. A persistent `.on` listener would still be registered
+// when the `process.kill(process.pid, result.signal)` re-raise below runs at
+// shutdown, swallowing it and leaving this launcher exiting 0 instead of
+// reflecting the child's signal. `.once` consumes only the
+// externally-delivered signal that triggers the forward, so the re-raise
+// correctly falls through to the OS default.
+for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"]) {
+  const handler = () => forwardSignal(signal);
+  forwardHandlers.set(signal, handler);
+  process.once(signal, handler);
+}
+
 // A scheduled row sets its environment itself (a cron `VAR=value` prefix, a
 // launchd plist's EnvironmentVariables), and the scheduler supplies PATH, so
 // runtime selection below needs nothing from it. A row written by 0.9.0 –
@@ -42,13 +84,21 @@ const bunEntry = fileURLToPath(new URL("./cli.js", import.meta.url));
 const nodeEntry = fileURLToPath(new URL("./cli-node.mjs", import.meta.url));
 
 if (!useBun && !process.versions.bun) {
-  await import("./cli-node.mjs");
+  // No child is ever spawned on this path — the imported module runs
+  // in-process, so it IS the work, and the runtime's ordinary default signal
+  // disposition is exactly correct for it. Hand that back (the forwarding
+  // listeners above no longer apply here), re-raising anything that already
+  // arrived so it is not silently swallowed by a listener that now does
+  // nothing.
+  for (const [signal, handler] of forwardHandlers) process.removeListener(signal, handler);
+  if (pendingSignals.length > 0) process.kill(process.pid, pendingSignals[0]);
+  else await import("./cli-node.mjs");
 } else {
   const command = useBun ? (process.versions.bun ? process.execPath : "bun") : "node";
   const entry = useBun ? bunEntry : nodeEntry;
   const runtime = useBun ? "Bun" : "Node.js";
   const result = await new Promise((resolve) => {
-    const child = spawn(command, [entry, ...process.argv.slice(2)], {
+    child = spawn(command, [entry, ...process.argv.slice(2)], {
       stdio: "inherit",
       env: process.env,
       // #956: give the child its OWN process group on POSIX (`setsid()` —
@@ -75,29 +125,12 @@ if (!useBun && !process.versions.bun) {
     // forward once the child has already exited: forwarding to a
     // dead/replaced pid would be at best a no-op and at worst a signal to
     // an unrelated process that reused the pid.
-    let childExited = false;
     child.once("exit", () => {
       childExited = true;
     });
-    const forwardSignal = (signal) => {
-      if (childExited) return;
-      try {
-        child.kill(signal);
-      } catch {
-        // Child exited in the race between the check above and here.
-      }
-    };
-    // `.once`, not `.on`: Node/Bun suppress a signal's default
-    // (process-terminating) disposition for as long as ANY listener stays
-    // registered for it. A persistent `.on` listener would still be
-    // registered when the `process.kill(process.pid, result.signal)`
-    // re-raise below runs at shutdown, swallowing it and leaving this
-    // launcher exiting 0 instead of reflecting the child's signal. `.once`
-    // consumes only the externally-delivered signal that triggers the
-    // forward, so the re-raise correctly falls through to the OS default.
-    for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"]) {
-      process.once(signal, () => forwardSignal(signal));
-    }
+    // Flush whatever arrived in the (now much smaller) window between the
+    // listeners going up and the child existing to receive them.
+    for (const signal of pendingSignals.splice(0)) forwardSignal(signal);
     child.once("error", (error) => resolve({ error }));
     child.once("exit", (code, signal) => resolve({ code, signal }));
   });

package/dist/akm-migrate

@@ -6,6 +6,40 @@
 import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
+// #956 round 3: install the signal-forwarding scaffolding before ANYTHING
+// else in this process — the Node-version check, the bun-version probe,
+// spawning the child — gets a chance to run. See the matching fix and
+// comment in scripts/node-runtime/akm: the three `process.once` listeners
+// used to go up only after spawn() (below) returned; a scheduler preemption
+// right after that syscall was enough for a signal to arrive with no
+// listener yet, and the runtime's default (process-terminating) disposition
+// killed the launcher outright, never reaching the child at all. `child`
+// starts unset: a signal that arrives before it exists is queued and
+// flushed the moment it does.
+let child;
+let childExited = false;
+const pendingSignals = [];
+const forwardSignal = (signal) => {
+  if (childExited) return;
+  if (!child) {
+    pendingSignals.push(signal);
+    return;
+  }
+  try {
+    child.kill(signal);
+  } catch {
+    // Child exited in the race between the check above and here.
+  }
+};
+// `.once`, not `.on`: see the matching comment in scripts/node-runtime/akm —
+// a persistent `.on` listener would still be registered when the
+// `process.kill(process.pid, result.signal)` re-raise below runs,
+// suppressing the OS default disposition and leaving this launcher exiting
+// 0 instead of reflecting the child's signal.
+for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"]) {
+  process.once(signal, () => forwardSignal(signal));
+}
+
 if (!process.versions.bun) {
   const [major = 0, minor = 0] = process.versions.node.split(".").map(Number);
   if (major < 22) {
@@ -34,7 +68,7 @@ const nodeEntry = fileURLToPath(new URL("./scripts/akm-migrate-node.js", import.
   const command = process.versions.bun ? process.execPath : useBun ? "bun" : process.execPath;
   const entry = process.versions.bun || useBun ? bunEntry : nodeEntry;
   const result = await new Promise((resolve) => {
-    const child = spawn(command, [entry, ...process.argv.slice(2)], {
+    child = spawn(command, [entry, ...process.argv.slice(2)], {
       stdio: "inherit",
       env,
       // #956: own process group on POSIX so the launcher's forward below is
@@ -43,27 +77,12 @@ const nodeEntry = fileURLToPath(new URL("./scripts/akm-migrate-node.js", import.
       // directly — see the matching comment in scripts/node-runtime/akm.
       detached: process.platform !== "win32",
     });
-    let childExited = false;
     child.once("exit", () => {
       childExited = true;
     });
-    const forwardSignal = (signal) => {
-      if (childExited) return;
-      try {
-        child.kill(signal);
-      } catch {
-        // Child exited in the race between the check above and here.
-      }
-    };
-    // `.once`, not `.on`: see the matching comment in
-    // scripts/node-runtime/akm — a persistent `.on` listener would still be
-    // registered when the `process.kill(process.pid, result.signal)`
-    // re-raise below runs, suppressing the OS default disposition and
-    // leaving this launcher exiting 0 instead of reflecting the child's
-    // signal.
-    for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"]) {
-      process.once(signal, () => forwardSignal(signal));
-    }
+    // Flush whatever arrived in the (now much smaller) window between the
+    // listeners going up and the child existing to receive them.
+    for (const signal of pendingSignals.splice(0)) forwardSignal(signal);
     child.once("error", (error) => resolve({ error }));
     child.once("exit", (code, signal) => resolve({ code, signal }));
   });

package/dist/assets/stash-skeleton/facts/conventions/backlinks.md

@@ -3,7 +3,7 @@ type: fact
 category: convention
 description: How to cross-link assets so retrieval compounds — a provenance xref when derived, sparse real associative xrefs, corrections as new assets, and canonical entity naming.
 when_to_use: Surfaced to authoring agents when they create or revise any asset that derives from, corrects, or relates to another asset.
-updated: 2026-07-28
+updated: 2026-09-28
 ---
 
 <!--
@@ -19,8 +19,10 @@ updated: 2026-07-28
 
 Cross-references are how knowledge compounds instead of being re-derived every
 session. In AKM they are also **indexed**: the strings in an asset's `xrefs:`
-frontmatter fold into its search-hint text, and knowledge/memory bodies feed an
-LLM-extracted entity/relation graph that boosts ranking. So links are a retrieval
+frontmatter fold into its search-hint text and are stored as links that
+`akm show` lists on both assets (with `supersededBy:`, `contradictedBy:` and a
+`.derived` memory's parent), and knowledge/memory bodies feed an LLM-extracted
+entity/relation graph that boosts ranking. So links are a retrieval
 lever — which means both too few and too many hurt.
 
 ```yaml

package/dist/commands/improve/loop-stages.js

@@ -475,15 +475,16 @@ export async function runMemoryInferenceMaintenancePass(ctx, dbCell, memoryRefsF
 export async function runGraphExtractionMaintenancePass(ctx, dbCell, args) {
     const { config, sources, primaryStashDir, resolvedPlan } = ctx;
     const settings = ctx.improveProfile?.processes?.graphExtraction;
-    const graphEnabled = resolvedPlan ? true : isProcessEnabled("index", "graph_extraction", config);
     if (settings?.enabled === false) {
         info("[improve] graph extraction skipped (disabled by improve profile)");
         return { durationMs: 0, warnings: [] };
     }
     if (sources.length === 0)
         return { durationMs: 0, warnings: [] };
-    if (!graphEnabled) {
-        info("[improve] graph extraction skipped (features.index.graph_extraction is disabled)");
+    // `index.graph.enabled: false` turns graph extraction off everywhere,
+    // whatever the strategy enables.
+    if (!isProcessEnabled("index", "graph_extraction", config)) {
+        info("[improve] graph extraction skipped (index.graph.enabled is false)");
         return { durationMs: 0, warnings: [] };
     }
     const fullScan = settings?.fullScan === true;

package/dist/commands/read/curate.js

@@ -9,12 +9,15 @@
  * needed to act (ref, run, parameters, follow-up command).
  *
  * Curation is one search with the fused ranking, the top `limit` hits, and
- * per-hit enrichment (preview, run and parameters, graph support refs). An
- * optional reranker reorders the top fused candidates first.
+ * per-hit enrichment (preview, run and parameters, support refs from the
+ * hit's declared links). An optional reranker reorders the top fused
+ * candidates first.
  *
  * The exported `akmCurate()` API is the single entry point; tests can also
  * drive `curateSearchResults` with a fixture search response.
  */
+import { parseBundleRef } from "../../core/asset/asset-ref.js";
+import { typeNameFromConceptId } from "../../core/asset/resolve-ref.js";
 import { loadConfig } from "../../core/config/config.js";
 import { rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
@@ -212,7 +215,7 @@ async function enrichCuratedStashHit(query, hit, selectedRefs, eventSource) {
     }
     const description = shown?.description ?? hit.description;
     const preview = buildCuratedPreview(shown, hit);
-    const supportRefs = buildCurateSupportRefs(shown?.related?.hits, selectedRefs, hit.ref);
+    const supportRefs = buildCurateSupportRefs(shown?.links, selectedRefs, hit.ref);
     const item = {
         source: "local",
         type: shown?.type ?? hit.type,
@@ -324,17 +327,41 @@ async function maybeRerankCuratedStashHits(query, hits) {
 function rerankDocumentTexts(hits) {
     return hits.map((hit) => [hit.name, hit.description, searchHitContent(hit)].filter(Boolean).join("\n").slice(0, RERANK_DOCUMENT_CHARS));
 }
-/** Up to {@link MAX_CURATE_SUPPORT_REFS} graph-related assets not already selected. */
-function buildCurateSupportRefs(relatedHits, selectedRefs, ownerRef) {
+/**
+ * Up to {@link MAX_CURATE_SUPPORT_REFS} assets the hit's declared links (#935)
+ * name, not already selected: what the hit links to first, then what links to
+ * it, in the order `akm show` lists them. The LLM entity graph's `related`
+ * list no longer feeds them.
+ */
+function buildCurateSupportRefs(links, selectedRefs, ownerRef) {
     const supportRefs = [];
-    for (const hit of relatedHits ?? []) {
-        if (!hit.ref || hit.ref === ownerRef || selectedRefs.has(hit.ref))
-            continue;
-        if (supportRefs.some((existing) => existing.ref === hit.ref))
-            continue;
-        supportRefs.push({ ref: hit.ref, type: hit.type, reason: "Related asset via shared entities." });
-        if (supportRefs.length >= MAX_CURATE_SUPPORT_REFS)
-            break;
+    for (const [part, direction] of [
+        ["outgoing", "from"],
+        ["incoming", "to"],
+    ]) {
+        for (const [kind, group] of Object.entries(links?.[part] ?? {})) {
+            for (const ref of group.refs) {
+                if (ref === ownerRef || selectedRefs.has(ref) || supportRefs.some((existing) => existing.ref === ref))
+                    continue;
+                const type = supportRefType(ref);
+                supportRefs.push({
+                    ref,
+                    ...(type ? { type } : {}),
+                    reason: `Declared link (${kind}) ${direction} this asset.`,
+                });
+                if (supportRefs.length >= MAX_CURATE_SUPPORT_REFS)
+                    return supportRefs;
+            }
+        }
     }
     return supportRefs;
 }
+/** The asset type a ref's conceptId names (`memories/x` → `memory`), when it names one. */
+function supportRefType(ref) {
+    try {
+        return typeNameFromConceptId(parseBundleRef(ref).conceptId)?.type;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/commands/read/show.js

@@ -24,7 +24,7 @@ import { makeBundleRef, parseBundleRef } from "../../core/asset/asset-ref.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { extractSection, markdownFragmentSlugs } from "../../core/asset/markdown.js";
 import { buildMarkdownLeadContext, fragmentForSelector, MARKDOWN_FRAGMENT_CONTEXT_DEFAULT_MAX_CHARS, } from "../../core/asset/markdown-fragments.js";
-import { displayRef, typeNameFromConceptId } from "../../core/asset/resolve-ref.js";
+import { displayRef, displayRefForConceptId, typeNameFromConceptId } from "../../core/asset/resolve-ref.js";
 import { META_DIR, parseMetaRef, readMetaFile } from "../../core/asset/stash-meta.js";
 import { asNonEmptyString, isWithin } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
@@ -43,6 +43,7 @@ import { buildFileContext, buildRenderContext, getRenderer, } from "../../indexe
 import { resolveSourcesForOrigin } from "../../registry/origin-resolve.js";
 import { withIndexDb } from "../../storage/repositories/index-db.js";
 import { getIndexedMarkdownFragment } from "../../storage/repositories/index-fts-repository.js";
+import { readEntryLinks } from "../../storage/repositories/index-links-repository.js";
 import { getCurrentWorkflowScopeKey } from "../../workflows/authoring/scope-key.js";
 import { buildWorkflowAction } from "../../workflows/renderer.js";
 import { getActiveWorkflowRun } from "../../workflows/runtime/runs.js";
@@ -318,12 +319,13 @@ export async function showLocal(input) {
     response.type = indexedEntry.type;
     response.name = indexedEntry.name;
     const isPrimaryStash = source?.isDefault === true;
+    const displayDefaultBundle = config.defaultBundle ?? (isPrimaryStash ? indexedEntry.bundleId : undefined);
     const canonicalRef = displayRef({
         type: indexedEntry.type,
         name: presentedName,
         conceptId: indexedEntry.conceptId,
         bundleId: indexedEntry.bundleId,
-    }, config.defaultBundle ?? (isPrimaryStash ? indexedEntry.bundleId : undefined));
+    }, displayDefaultBundle);
     if (parsed.fragment && indexedFragment) {
         const selectedFragmentId = indexedFragment.fragments[indexedFragment.ordinal].fragmentId;
         const selectedRef = `${canonicalRef}#${selectedFragmentId}`;
@@ -395,6 +397,7 @@ export async function showLocal(input) {
                 return { total: 0, hits: [] };
             }
         })(),
+        ...showLinks(indexedEntry.itemRef, displayDefaultBundle),
     };
     const activeRun = await getActiveWorkflowRun(getCurrentWorkflowScopeKey());
     if (activeRun) {
@@ -408,6 +411,56 @@ export async function showLocal(input) {
     }
     return fullResponse;
 }
+/** Refs listed per kind of declared link; `total` still counts them all (one memory is named by 1,437 others). */
+const LINKS_PER_KIND = 10;
+/**
+ * The declared links (#935) of an indexed asset, grouped by kind: outgoing in
+ * authored order, incoming by ref, and unresolved tokens as authored. Empty
+ * parts are omitted, and the field when nothing links either way.
+ */
+function showLinks(itemRef, defaultBundle) {
+    let rows;
+    try {
+        rows = withIndexDb((db) => readEntryLinks(db, itemRef));
+    }
+    catch (err) {
+        rethrowIfTestIsolationError(err);
+        rethrowIfDataDirUnreadable(err);
+        return {};
+    }
+    const outgoing = [];
+    const unresolved = [];
+    for (const row of rows.outgoing) {
+        if (row.conceptId === undefined)
+            unresolved.push({ kind: row.kind, ref: row.raw ?? "" });
+        else
+            outgoing.push({ kind: row.kind, ref: displayRefForConceptId(row.conceptId, row.bundleId, defaultBundle) });
+    }
+    const incoming = rows.incoming.map((row) => ({
+        kind: row.kind,
+        ref: displayRefForConceptId(row.conceptId ?? "", row.bundleId, defaultBundle),
+    }));
+    const links = {
+        ...groupLinks("outgoing", outgoing),
+        ...groupLinks("incoming", incoming),
+        ...groupLinks("unresolved", unresolved),
+    };
+    return Object.keys(links).length > 0 ? { links } : {};
+}
+function groupLinks(part, rows) {
+    if (rows.length === 0)
+        return {};
+    const groups = {};
+    for (const kind of [...new Set(rows.map((row) => row.kind))].sort())
+        groups[kind] = { total: 0, refs: [] };
+    for (const { kind, ref } of rows) {
+        const group = groups[kind];
+        group.total++;
+        if (group.refs.length < LINKS_PER_KIND)
+            group.refs.push(ref);
+    }
+    return { [part]: groups };
+}
 /**
  * Warn and ignore body fragments for namespaces whose authored bytes are
  * sensitive. `warnOnce`-keyed on the exact ref: `akmShowUnified` calls this

package/dist/commands/sources/info.js

@@ -10,6 +10,7 @@ import { formatRegistryUrl } from "../../core/registry-url.js";
 import { error } from "../../core/warn.js";
 import { closeDatabase, openExistingDatabase } from "../../storage/repositories/index-connection.js";
 import { getEntryCount, getEntryCountByType } from "../../storage/repositories/index-entries-repository.js";
+import { countLinksByKind } from "../../storage/repositories/index-links-repository.js";
 import { getMeta } from "../../storage/repositories/index-meta-repository.js";
 import { pkgVersion } from "../../version.js";
 /**
@@ -99,9 +100,11 @@ function readIndexStats(resolvedPath) {
     let db;
     try {
         db = openExistingDatabase(resolvedPath);
+        const links = countLinksByKind(db);
         return {
             entryCount: getEntryCount(db),
             byType: getEntryCountByType(db),
+            ...(Object.keys(links).length > 0 ? { links } : {}),
             lastBuiltAt: getMeta(db, "builtAt") ?? null,
             hasEmbeddings: getMeta(db, "hasEmbeddings") === "1",
         };

package/dist/core/adapter/adapters/akm-adapter.js

@@ -193,6 +193,8 @@ const DOCUMENT_JSON_CARRIED_FIELDS = [
     "wikiRole",
     "sources",
     "evidenceSources",
+    // #935: a workflow's step targets and a task's target, read as declared links.
+    "uses",
     // D2 (#730): the OKF v0.2 provenance `promoteProposal` stamps onto AKM-native
     // writes (generated/verified/sources, namespaced — see `types.ts`'s
     // `OkfProvenance` doc). Carried so the akm adapter rereads what it wrote and

package/dist/core/adapter/adapters/akm-metadata.js

@@ -54,6 +54,7 @@
  * concern (Chunk 4/5), not recognition's. On the valid Chunk-0b fixture this
  * distinction never triggers.
  */
+import { parseBuiltinCommandAction } from "../../../commands/command/builtin-action.js";
 import { scanEnvKeyNames } from "../../../commands/env/env.js";
 import { parseTaskSource } from "../../../tasks/source/parse-task-source.js";
 import { compileWorkflowSource, workflowStepInstructions } from "../../../workflows/compile.js";
@@ -125,6 +126,25 @@ function applyFrontmatterDescriptionAndTags(fm, out) {
         }
     }
 }
+/** The command a stored `akm/command` action runs; inline content names no asset. */
+function storedCommandRef(action) {
+    return action?.kind === "stored" ? action.ref : undefined;
+}
+/** The asset a workflow step targets: its `uses:` ref, or the ref of a stored `akm/command`. Prose and `run:` steps target none. */
+function workflowStepTarget(spec) {
+    if (!spec?.uses)
+        return undefined;
+    if (spec.uses !== "akm/command")
+        return spec.uses;
+    if (spec.commandMode !== "stored-ref")
+        return undefined;
+    try {
+        return storedCommandRef(parseBuiltinCommandAction(spec.with));
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Collect + finalize a searchHints set the way every contributor does (`Array.from(hints).filter(Boolean)`, assigned only when non-empty). */
 function finalizeHints(out, hints) {
     if (hints.size > 0)
@@ -245,6 +265,9 @@ export function foldRecognizedMetadata(rendererName, file) {
                         hints.add(`prompt:${target.command.ref}`);
                     else
                         hints.add(`uses:${target.uses.ref}`);
+                    const used = target.uses.kind !== "builtin-command" ? target.uses.ref : storedCommandRef(target.command);
+                    if (used)
+                        out.uses = [used];
                 }
                 else {
                     hints.add(`run:${target.run}`);
@@ -321,6 +344,7 @@ export function foldRecognizedMetadata(rendererName, file) {
                     return out;
                 const plan = result.plan;
                 const hints = new Set();
+                const uses = new Set();
                 if (plan.preamble)
                     hints.add(plan.preamble);
                 for (const step of plan.steps) {
@@ -328,8 +352,13 @@ export function foldRecognizedMetadata(rendererName, file) {
                     hints.add(workflowStepInstructions(step));
                     if (step.gate.criteria[0])
                         hints.add(step.gate.criteria[0]);
+                    const used = workflowStepTarget(step.spec);
+                    if (used)
+                        uses.add(used);
                 }
                 out.searchHints = Array.from(hints).filter(Boolean);
+                if (uses.size > 0)
+                    out.uses = [...uses];
                 if (plan.paramSchemas) {
                     const parameters = Object.entries(plan.paramSchemas).map(([name, schema]) => {
                         const description = schema.description;
@@ -395,4 +424,6 @@ export function applyFoldedMetadata(entry, folded) {
         entry.toc = folded.toc;
     if (folded.parameters)
         entry.parameters = folded.parameters;
+    if (folded.uses)
+        entry.uses = folded.uses;
 }