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

package/CHANGELOG.md

@@ -6,6 +6,171 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.17-alpha.6] - 2026-09-27
+
+Graph extraction stops losing and wasting work. A timed-out extraction is
+retried instead of cached as empty. Long documents are extracted once, and
+per-file calls respect the run's concurrency. `akm improve` honors
+`index.graph`. `akm curate` returns nothing for harness and tool envelopes,
+and search and curate show identical content once. Lazy graph extraction,
+which never ran under Bun, is removed.
+
+### Changed
+
+- **`akm curate` returns nothing, on purpose, for input that is not a task.**
+  A harness or tool envelope (input that starts with an XML-style tag and
+  contains a closing tag, such as `<task-notification>…</task-notification>`,
+  `<system-reminder>…` or `<cross-session-message …>…`) and the stash README
+  line each used to get `--limit` unrelated assets. Every caller of
+  `akm curate` (the CLI, the OpenCode plugin, other harnesses) now gets an
+  empty `items` list with a `summary` that starts with `Curate abstained` and
+  names the reason, and a `tip`. On the retrieval suite curate abstains on 57
+  of 60 recorded non-task inputs and on none of the 221 real queries (nor on
+  any of 5,725 mined task queries). Length is not a reason to abstain: the
+  other 3 are task prompts of 2,431–5,531 characters, and in a judged sample
+  of 30 inputs over 2,000 characters the top 5 held a relevant asset for 24
+  of them (P@5 0.42, against 0.46 for prompts of 400–2,000 characters).
+  (`src/commands/read/curate.ts`)
+- **Search and curate return identical content once.** Of entries whose
+  indexed content is identical (the same body saved under another name, as
+  both a memory and a knowledge doc, or in another bundle), only the
+  highest-ranked is kept, and the next candidate takes the freed slot. On the
+  retrieval suite such copies filled 7.5% of curate's top 5. Unique
+  precision@5, where a copy of a higher-ranked result earns nothing, rises
+  from 0.467 to 0.514 (+0.046, 95% CI [+0.028, +0.067]), and the share of
+  top-5 slots that repeat a higher-ranked result falls from 0.131 to 0.055.
+  Plain P@5 (0.553 → 0.551) and nDCG@10 stay within noise: they counted each
+  copy as another relevant result. Latency is unchanged.
+  (`src/indexer/search/db-search.ts`)
+
+### Removed
+
+- **The unused `utility_scores_scoped` index table is gone.** It shipped in
+  0.9.17-alpha.5 for per-project scoped utility scores, but no code ever read
+  or wrote a row. An index database drops it on its next writable open, the
+  same way other retired derived tables are dropped, with no layout-version
+  change. (`src/storage/repositories/index-schema.ts`)
+- **Lazy graph extraction in `akm show` and `akm curate`.** With
+  `index.graph.lazyGraphExtraction: true`, `show` extracted an asset's graph
+  after building its response, so only the next `show` saw it. `curate`
+  queued assets for a later pass, which drained only the working bundle's
+  queue, and extractions made this way wrote no cache entry. Under Bun neither
+  path ever ran: the "already has a graph" check read a missing row as
+  present. Graph extraction now runs only in `akm improve`. The
+  `graph_extraction_queue` table is dropped the next time the index is opened
+  for writing. A config that still sets the key loads, and the key is named
+  once as unknown. (`src/commands/read/show.ts`,
+  `src/commands/read/curate.ts`, `src/indexer/graph/graph-extraction.ts`,
+  `src/storage/repositories/index-schema.ts`)
+
+### Fixed
+
+- **`index.metadataEnhance`'s default is no longer contradicted by dead
+  code.** Metadata enhancement has always defaulted to off
+  (`isLlmFeatureEnabled`); a second, unreachable code path in
+  `isProcessEnabled` claimed the opposite default and had no caller. Removed,
+  so one default remains. (`src/llm/feature-gate.ts`)
+- **Eval tooling and docs catch up to the current config and index shape.**
+  `scripts/akm-eval/src/curate-bench.ts` wrote the retired `sources` config
+  key and called a nonexistent `akm index --dir`; it now seeds its sandbox
+  the same way the other akm-eval scripts and integration tests do, and
+  drops `--dir`. The graph A/B ablation harness
+  (`scripts/akm-eval/src/graph-ablation.ts`) planted its "graph off" config
+  where the sandboxed `akm` never read it, with config keys that didn't gate
+  anything (one of them a type error); it now writes
+  `index.graph.enabled: false` to the sandbox's actual `AKM_CONFIG_DIR`.
+  Updated `scripts/akm-eval/README.md` and `docs/maintainers/eval.md` to
+  match, and corrected stale `docs/architecture/architecture.md` references
+  to `db-backup`, `staleness-detect`, and `src/commands/graph/`.
+- **Scheduled graph extraction reads `index.graph`.** `akm improve` passed
+  graph extraction a batch size of 4 and the `memory` and `knowledge` types
+  whenever the strategy's `processes.graphExtraction` did not set them, so
+  `index.graph.graphExtractionBatchSize` and `graphExtractionIncludeTypes`
+  never applied. It did not read `index.graph`'s `engine`, `model`,
+  `timeoutMs` or `llm` either, so a setting such as
+  `index.graph.llm.enableThinking: false` had no effect on improve runs. A
+  value in the strategy's `processes.graphExtraction` still wins. A setting it
+  leaves unset now comes from `index.graph`, then from the built-in default.
+  Where `index.graph` asks for something improve did not use before, the
+  extractor changes and cached extractions stop applying, so those files are
+  extracted again. (`src/commands/improve/loop-stages.ts`,
+  `src/commands/improve/execution.ts`,
+  `src/commands/improve/improve-strategies.ts`)
+- **A graph extraction that times out is retried, not cached as empty.** A
+  call that ran past the engine's `timeoutMs` was recorded as "no entities"
+  and cached, so the file was never extracted again. It is now recorded as
+  failed, and the next run retries it; timeouts also count toward the run's
+  failure-rate abort. A batch that times out fails its files without then
+  calling the model once per file. An empty response is likewise recorded as
+  failed. (`src/llm/graph-extract.ts`)
+- **Long bodies are extracted once after batching turns itself off.** Two
+  non-array batch responses turn batching off for the rest of a run. From
+  then on, a body over 1,600 characters was extracted on its own and then
+  again with the rest of its batch. Each body is now extracted once.
+  (`src/llm/graph-extract.ts`)
+- **A batch's per-file calls respect the run's concurrency.** When a batch
+  fell back to one call per file (long bodies, a non-array response, batching
+  turned off), those calls all went out at once, up to the batch size. Local
+  endpoints serve one or two requests at a time. The calls now run within the
+  limit the run applies to its batches, one at a time by default.
+  (`src/llm/graph-extract.ts`)
+- **`related` counts a shared entity once.** `akm show`'s `related` list,
+  and curate's support refs taken from it, ranked files by the number of
+  matching entity rows. A file holding two case forms of one entity, as rows
+  from older extractors can, counted it twice and could outrank a file that
+  shared two entities. `related` now counts distinct entities. Extraction also
+  keeps one form of each entity before writing. The stored key `related`
+  matches on is now the one extraction deduplicates on, which also drops
+  surrounding quotes and backticks.
+  (`src/indexer/graph/graph-related.ts`,
+  `src/indexer/graph/graph-extraction.ts`, `src/indexer/db/graph-db.ts`)
+- **A config change that re-extracts the graph says so.** Cached graph
+  extractions are keyed by extractor: model, batch size, included asset types
+  and prompt version. Changing any of them made every cached file extract
+  again without a word. The first run after such a change now warns once,
+  naming the change and the number of cached files it will extract again, and
+  records the warning in the run's result.
+  (`src/indexer/graph/graph-extraction.ts`)
+- **Graph extraction reports what its parser filtered.** A run's graph
+  telemetry, part of `akm improve`'s result, now carries
+  `filteredGenericEntities`, `filteredInvalidRelations`,
+  `filteredLowConfidenceRelations` and `contextBatchRetries`. The pass
+  computed them and dropped them, and did not count batch responses at all.
+  (`src/indexer/graph/graph-extraction.ts`, `src/llm/graph-extract.ts`)
+- **An unknown key under `index.<pass>` is kept and named once.** It was
+  dropped from the loaded config and named twice. It is now handled like an
+  unknown key anywhere else in config. (`src/core/config/schema/index-config.ts`)
+
+## [0.9.17-alpha.5] - 2026-09-27
+
+`akm show` works again for a memory that has a `.derived.md` child (835 of them
+in one real bundle), and `akm bundle add --provider … --name` holds to the same
+`--name` contract as every other add.
+
+### Fixed
+
+- **`akm show` works for a memory that has a `.derived.md` child.** When
+  `memories/X.md` and `memories/X.derived.md` both existed, `akm show
+  memories/X`, with or without a `#fragment`, failed with
+  `RESOURCE_ALREADY_EXISTS` ("multiple physical owners"); `akm curate`
+  previewed such a memory from its description alone, and `akm curate --pack`
+  left it out. The index gives the derived child its own ref,
+  `memories/X.derived`, but the ref lookup also counted `X.derived.md` as a
+  file for `memories/X`. The lookup now follows the index: `memories/X` is
+  `X.md` and `memories/X.derived` is `X.derived.md`. A derived child whose
+  parent file is gone no longer answers for the parent's ref either, so it
+  cannot hide a real `X.md` in a lower-priority bundle. `akm lint` and
+  `--xref` / `--supersedes` validation still accept a ref to `memories/X`
+  when only `X.derived.md` remains. Broken since 0.9.7.
+  (`src/core/asset/asset-placement.ts`, `src/commands/lint/base-linter.ts`)
+- **`akm bundle add --provider … --name` keeps the `--name` contract too.**
+  Since 0.9.17-alpha.4 an explicit `--name` that is not a legal bundle slug,
+  or is taken by another bundle, fails with exit 2, and re-adding a source
+  under a different name points at `akm bundle rename`. A declarative add
+  (`akm bundle add <target> --provider npm|git|website`) still replaced such
+  a name with a derived one and exited 0. It now fails the same way, before
+  any write. (`src/commands/sources/source-manage.ts`)
+
 ## [0.9.17-alpha.4] - 2026-09-27
 
 Search and curate are rebuilt on measured evidence. On a 221-query suite of real
@@ -640,9 +805,8 @@ config migration, and it lands with fewer lines in `src/` than 0.9.17-alpha.3.
   documented for `registryId`. The key used to come from the basename of the
   cache directory the package was unpacked into, which is always `extracted`,
   so every registry bundle after the first was `extracted-<hash>`. A dotted
-  or mixed-case name is slugged like a directory name (`Foo.js` → `foo-js`),
-  and a `--name` that is not a legal bundle slug now falls back to this name
-  too. Bundles that are already installed keep their current key, including
+  or mixed-case name is slugged like a directory name (`Foo.js` → `foo-js`).
+  Bundles that are already installed keep their current key, including
   `extracted`, because every recorded `extracted//…` ref depends on it.
 - **A one-file change in a large directory no longer costs `akm index` half
   an hour.** Both full-text tables keyed their per-entry deletes on

package/dist/commands/improve/execution.js

@@ -20,19 +20,19 @@ function mergeDefaults(farther, nearer) {
     return deepMergeConfig(farther, nearer);
 }
 /**
- * Resolve improve-owned model work through the canonical execution cascade.
- * The legacy improve precedence is preserved exactly:
- * defaults.llmEngine -> strategy -> process -> current invocation.
+ * Resolve improve-owned model work through the canonical execution cascade:
+ * defaults.llmEngine -> strategy -> index.<pass> -> process -> current invocation.
  */
 export function resolveImproveExecution(options) {
     const defaultEngine = options.config.defaults?.llmEngine;
     const profileDefaults = cascadeDefaults(options.profile);
+    const indexDefaults = cascadeDefaults(options.index);
     const processDefaults = cascadeDefaults(options.process);
     const currentDefaults = cascadeDefaults(options.current);
-    const selectedEngine = currentDefaults.engine ?? processDefaults.engine ?? profileDefaults.engine ?? defaultEngine;
+    const selectedEngine = currentDefaults.engine ?? processDefaults.engine ?? indexDefaults.engine ?? profileDefaults.engine ?? defaultEngine;
     if (selectedEngine === undefined || selectedEngine === null)
         return null;
-    const invocationDefaults = mergeDefaults(defaultEngine ? { engine: defaultEngine } : {}, profileDefaults);
+    const invocationDefaults = mergeDefaults(mergeDefaults(defaultEngine ? { engine: defaultEngine } : {}, profileDefaults), indexDefaults);
     const current = mergeDefaults(processDefaults, currentDefaults);
     const prepared = resolveExecution({
         content: `improve ${options.processName} execution selection`,

package/dist/commands/improve/improve-strategies.js

@@ -10,6 +10,7 @@ import quick from "../../assets/improve-strategies/quick.json" with { type: "jso
 import reflectDistill from "../../assets/improve-strategies/reflect-distill.json" with { type: "json" };
 import thorough from "../../assets/improve-strategies/thorough.json" with { type: "json" };
 import { conceptIdFromTypeName, parseRefInput } from "../../core/asset/resolve-ref.js";
+import { getIndexPassConfig, } from "../../core/config/config.js";
 import { ImproveProfileConfigSchema } from "../../core/config/config-schema.js";
 import { deepMergeConfig } from "../../core/config/deep-merge.js";
 import { BUILTIN_IMPROVE_STRATEGY_NAMES, IMPROVE_PROCESS_ENGINE_CAPABILITIES, } from "../../core/config/engine-semantics.js";
@@ -211,6 +212,8 @@ function buildImprovePlan(strategy, config, options) {
                 profile: strategy.config,
                 process: sourceProcessConfig,
                 processName,
+                // Graph extraction's standing engine, model, timeout and llm settings (GR-D15).
+                ...(processName === "graphExtraction" ? { index: getIndexPassConfig(config.index, "graph") } : {}),
             });
             runner = resolved?.runner ?? null;
             notices = resolved?.notices ?? [];

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

@@ -6,14 +6,14 @@ import fs from "node:fs";
 import path from "node:path";
 import { parseRefInput } from "../../core/asset/resolve-ref.js";
 import { daysToMs } from "../../core/common.js";
-import { DEFAULT_GRAPH_EXTRACTION_BATCH_SIZE, loadConfig, } from "../../core/config/config.js";
+import { loadConfig } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { openLogsDatabase, purgeOldTaskLogs } from "../../core/logs-db.js";
 import { getDbPath, getTaskLogDir } from "../../core/paths.js";
 import { withStateDb } from "../../core/state-db.js";
 import { info } from "../../core/warn.js";
-import { DEFAULT_GRAPH_EXTRACTION_INCLUDE_TYPES, runGraphExtractionPass, } from "../../indexer/graph/graph-extraction.js";
+import { runGraphExtractionPass } from "../../indexer/graph/graph-extraction.js";
 import { indexWrittenAssets } from "../../indexer/index-written-assets.js";
 import { deriveWritableBundleIds } from "../../indexer/installations.js";
 import { collectPendingMemories, runMemoryInferencePass, } from "../../indexer/passes/memory-inference.js";
@@ -514,8 +514,9 @@ export async function runGraphExtractionMaintenancePass(ctx, dbCell, args) {
             },
             options: {
                 candidatePaths,
-                includeTypes: settings?.includeTypes ?? [...DEFAULT_GRAPH_EXTRACTION_INCLUDE_TYPES],
-                batchSize: settings?.batchSize ?? DEFAULT_GRAPH_EXTRACTION_BATCH_SIZE,
+                // Only what the strategy sets: the pass falls back to index.graph, then its defaults (GR-D15).
+                ...(settings?.includeTypes ? { includeTypes: settings.includeTypes } : {}),
+                ...(settings?.batchSize != null ? { batchSize: settings.batchSize } : {}),
                 ...(settings?.topN != null ? { topN: settings.topN } : {}),
                 ...(settings?.maxChunksPerAsset != null ? { maxChunksPerAsset: settings.maxChunksPerAsset } : {}),
             },

package/dist/commands/lint/base-linter.js

@@ -42,6 +42,7 @@ import { isArchivedRelPath } from "../../core/asset/memory-archive.js";
 import { conceptIdFromTypeName, typeNameFromConceptId } from "../../core/asset/resolve-ref.js";
 import { localDateStamp } from "../../core/common.js";
 import { containsRedactedContent, REDACTED_CONTENT_MARKER } from "../../core/content-safety.js";
+import { DERIVED_SUFFIX } from "../../core/recognition-util.js";
 import { findFenceRegions } from "./markdown-insertion.js";
 // ── Helpers ───────────────────────────────────────────────────────────────────
 /** Fold physically wrapped prose the same way a YAML plain scalar does. */
@@ -216,10 +217,23 @@ export function refExistsInAnyStash(relPath, refType, refName, stashRoots) {
     // record while leaving the live stash untouched.
     return memoryArchiveHasRef(refType, refName, stashRoots);
 }
+/**
+ * The stash-relative files that satisfy a ref, in preference order: its own
+ * placement spellings, then, for a memory, the `<name>.derived.md` child (#882),
+ * so an edge to a parent whose plain `.md` is gone still reaches the child it was
+ * distilled into. This is lint's reachability rule only; the child owns
+ * `memories/<name>.derived`, never `memories/<name>`.
+ */
+function refPathCandidates(refType, typeDir, refName) {
+    const candidates = assetPathCandidatesForName(refType, typeDir, refName);
+    if (refType !== "memory" || refName.endsWith(DERIVED_SUFFIX))
+        return candidates;
+    return [...candidates, assetPathForName(refType, typeDir, `${refName}${DERIVED_SUFFIX}`)];
+}
 /**
  * True when `(refType, refName)` names a memory that prune archived in any
  * root. Mirrors `resolveRefPathInStash`'s candidate set so a ref that resolved
- * through the `.derived.md` twin (#882) still resolves once archived.
+ * through the `.derived.md` child (#882) still resolves once archived.
  */
 function memoryArchiveHasRef(refType, refName, stashRoots) {
     if (refType !== "memory")
@@ -227,7 +241,7 @@ function memoryArchiveHasRef(refType, refName, stashRoots) {
     const typeDir = stashDirFor(refType);
     if (typeDir === undefined)
         return false;
-    const candidates = assetPathCandidatesForName(refType, typeDir, refName);
+    const candidates = refPathCandidates(refType, typeDir, refName);
     for (const root of stashRoots) {
         for (const candidate of candidates) {
             if (isArchivedRelPath(candidate, root))
@@ -241,8 +255,8 @@ function memoryArchiveHasRef(refType, refName, stashRoots) {
  * the same reachability rules (in the same order) as
  * {@link refExistsInAnyStash}, which delegates here. Returns the absolute path
  * of the file that makes the ref "exist" — for a multi-file skill directory
- * that is its `SKILL.md` primary, for a `memory` ref its `.derived.md` twin
- * when the plain `.md` is absent (#882, see `assetPathCandidatesForName`) —
+ * that is its `SKILL.md` primary, for a `memory` ref its `.derived.md` child
+ * when the plain `.md` is absent (#882, see {@link refPathCandidates}) —
  * or `null` when the ref does not resolve in this root.
  *
  * Extracted for SPEC-5 (`--supersedes` demotion): write commands need the
@@ -253,7 +267,7 @@ function memoryArchiveHasRef(refType, refName, stashRoots) {
  */
 export function resolveRefPathInStash(relPath, refType, refName, root) {
     const typeDir = stashDirFor(refType);
-    const candidates = typeDir === undefined ? [relPath] : assetPathCandidatesForName(refType, typeDir, refName);
+    const candidates = typeDir === undefined ? [relPath] : refPathCandidates(refType, typeDir, refName);
     for (const candidate of candidates) {
         const absPath = path.join(root, candidate);
         if (fs.existsSync(absPath))

package/dist/commands/read/curate.js

@@ -15,17 +15,13 @@
  * The exported `akmCurate()` API is the single entry point; tests can also
  * drive `curateSearchResults` with a fixture search response.
  */
-import fs from "node:fs";
-import { parseFrontmatter } from "../../core/asset/frontmatter.js";
-import { getIndexPassConfig, loadConfig } from "../../core/config/config.js";
+import { loadConfig } from "../../core/config/config.js";
 import { rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { redactCredentialPatterns } from "../../core/redaction.js";
 import { withStateDbTelemetry } from "../../core/state-db.js";
-import { enqueueGraphExtraction, hasGraphData } from "../../indexer/db/graph-db.js";
 import { searchHitContent } from "../../indexer/search/db-search.js";
 import { copySearchHitAttribution, getSearchHitAttribution, usageEventAttributionMetadata, } from "../../indexer/search/search-attribution.js";
-import { findSourceForPath, resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { insertUsageEvent } from "../../indexer/usage/usage-events.js";
 import { estimateTokenCount } from "../../llm/embedders/remote.js";
 import { isLlmFeatureEnabled, tryLlmFeature } from "../../llm/feature-gate.js";
@@ -33,11 +29,12 @@ import { rerankDocuments } from "../../llm/rerank-client.js";
 import { truncateDescription } from "../../output/shapes/helpers.js";
 import { TELEMETRY_BUSY_TIMEOUT_MS, withIndexDb } from "../../storage/repositories/index-db.js";
 import { findEntryIdByRef, getItemRefById } from "../../storage/repositories/index-entries-repository.js";
-import { computeBodyHash } from "../../storage/repositories/index-llm-cache-repository.js";
 import { akmSearch, parseSearchSource } from "./search.js";
 import { akmShowUnified } from "./show.js";
 const DEFAULT_CURATE_LIMIT = 4;
 const MAX_CURATE_SUPPORT_REFS = 2;
+/** 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";
 /** Fused candidates the reranker reorders when `search.curateRerank.topN` is unset. */
 const DEFAULT_CURATE_RERANK_TOP_N = 30;
 /** Characters of name, description and content sent to the reranker per candidate. */
@@ -104,6 +101,19 @@ export async function akmCurate(options) {
     if (!trimmedQuery) {
         throw new UsageError('A curation query is required. Usage: akm curate "<task or prompt>" [--type <type>] [--limit <n>]', "MISSING_REQUIRED_ARGUMENT");
     }
+    const nonTask = nonTaskInput(trimmedQuery);
+    if (nonTask) {
+        const abstained = {
+            query: options.query,
+            summary: `Curate abstained: the input is ${nonTask}, not a task.`,
+            items: [],
+            tip: 'Nothing was selected on purpose. To curate for it, pass the task itself: akm curate "<what you are trying to do>".',
+        };
+        if (!options.skipLogging) {
+            logCurateEvent(options.query, abstained, options.eventSource, options.attributionProjection);
+        }
+        return abstained;
+    }
     const limit = options.limit && options.limit > 0 ? options.limit : DEFAULT_CURATE_LIMIT;
     const source = options.source ?? parseSearchSource("local");
     const searchResponse = options.searchResponse ??
@@ -121,6 +131,21 @@ export async function akmCurate(options) {
     }
     return result;
 }
+/**
+ * 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.
+ */
+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;
+}
 export async function curateSearchResults(query, result, limit, selectedType, eventSource) {
     const allStashHits = result.hits.filter((hit) => hit.type !== "registry");
     const registryHits = result.registryHits ?? [];
@@ -201,11 +226,6 @@ async function enrichCuratedStashHit(query, hit, selectedRefs, eventSource) {
     catch {
         shown = undefined;
     }
-    // #624-P3: when lazy graph extraction is opted in, enqueue an ungraphed
-    // asset for a later pass to extract. Fire-and-forget, non-blocking, NO inline
-    // extraction and NO LLM call here. Default-off (flag unset) = byte-identical.
-    if (shown?.path)
-        maybeEnqueueLazyGraph(shown.path);
     const description = shown?.description ?? hit.description;
     const preview = buildCuratedPreview(shown, hit);
     const supportRefs = buildCurateSupportRefs(shown?.related?.hits, selectedRefs, hit.ref);
@@ -232,44 +252,6 @@ async function enrichCuratedStashHit(query, hit, selectedRefs, eventSource) {
     copySearchHitAttribution(hit, item, item.description);
     return item;
 }
-/**
- * #624-P3 — enqueue an ungraphed asset for lazy graph extraction when the
- * `index.graph.lazyGraphExtraction` flag is on. Pure side-effect, fully
- * best-effort: any failure (config, fs, db) is swallowed so curate never fails
- * on it. NO LLM call and NO inline extraction — only a cheap queue insert.
- * Default-off (flag unset) returns immediately = byte-identical behavior.
- */
-function maybeEnqueueLazyGraph(assetPath) {
-    try {
-        const config = loadConfig();
-        if (getIndexPassConfig(config.index, "graph")?.lazyGraphExtraction !== true)
-            return;
-        const sources = resolveSourceEntries();
-        const source = findSourceForPath(assetPath, sources);
-        const stashRoot = source?.path;
-        if (!stashRoot)
-            return;
-        let raw;
-        try {
-            raw = fs.readFileSync(assetPath, "utf8");
-        }
-        catch {
-            return;
-        }
-        const body = parseFrontmatter(raw).content.trim();
-        if (!body)
-            return;
-        const bodyHash = computeBodyHash(body);
-        withIndexDb((db) => {
-            if (!hasGraphData(db, stashRoot, assetPath)) {
-                enqueueGraphExtraction(db, stashRoot, assetPath, bodyHash, 0);
-            }
-        }, { busyTimeoutMs: TELEMETRY_BUSY_TIMEOUT_MS });
-    }
-    catch (err) {
-        rethrowIfTestIsolationError(err);
-    }
-}
 function buildCuratedRegistryItem(query, hit) {
     return {
         source: "registry",

package/dist/commands/read/show.js

@@ -27,14 +27,12 @@ import { buildMarkdownLeadContext, fragmentForSelector, MARKDOWN_FRAGMENT_CONTEX
 import { displayRef, 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 { getIndexPassConfig, loadConfig } from "../../core/config/config.js";
+import { loadConfig } from "../../core/config/config.js";
 import { NotFoundError, rethrowIfDataDirUnreadable, rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { SCRIPT_EXTENSIONS } from "../../core/recognition-util.js";
 import { presentationFor } from "../../core/type-presentation.js";
 import { warn, warnOnce } from "../../core/warn.js";
-import { hasGraphData } from "../../indexer/db/graph-db.js";
-import { extractGraphForSingleFile } from "../../indexer/graph/graph-extraction.js";
 import { listRelatedPathsForFile } from "../../indexer/graph/graph-related.js";
 import { lookupBundleRef, lookupBundleRefWithResolution } from "../../indexer/indexer.js";
 import { projectMarkdownFragmentContent } from "../../indexer/passes/metadata.js";
@@ -42,11 +40,8 @@ import { ensurePrimaryIndexForRead, resolveReadSources } from "../../indexer/rea
 import { buildEditHint, findSourceForPath, isEditable, resolveSourceEntries, } from "../../indexer/search/search-source.js";
 import { recentShowCount, recordShowUsage } from "../../indexer/usage/show-usage.js";
 import { buildFileContext, buildRenderContext, getRenderer, } from "../../indexer/walk/file-context.js";
-import { resolveIndexPassExecution } from "../../llm/index-passes.js";
 import { resolveSourcesForOrigin } from "../../registry/origin-resolve.js";
-import { resolveStorageLocations } from "../../storage/locations.js";
-import { closeDatabase, openExistingDatabase } from "../../storage/repositories/index-connection.js";
-import { TELEMETRY_BUSY_TIMEOUT_MS, withIndexDb } from "../../storage/repositories/index-db.js";
+import { withIndexDb } from "../../storage/repositories/index-db.js";
 import { getIndexedMarkdownFragment } from "../../storage/repositories/index-fts-repository.js";
 import { getCurrentWorkflowScopeKey } from "../../workflows/authoring/scope-key.js";
 import { buildWorkflowAction } from "../../workflows/renderer.js";
@@ -405,15 +400,6 @@ export async function showLocal(input) {
     if (activeRun) {
         fullResponse.activeRun = activeRun;
     }
-    // #624-P3: opt-in inline graph extraction. Default OFF — when the flag is
-    // unset this whole block is skipped (no hasGraphData check, no LLM call), so
-    // behavior is byte-identical to today. When ON, it extracts graph data for an
-    // ungraphed asset, but ONLY when a model is configured (model-available
-    // guard) and ALWAYS bounded by a 30s timeout so `show` can never hang. Any
-    // timeout/model-unavailable/error path returns the response unchanged.
-    if (getIndexPassConfig(config.index, "graph")?.lazyGraphExtraction === true) {
-        await maybeExtractGraphInline(config, sourceStashDir, assetPath);
-    }
     if (input.detail === "brief") {
         return buildBriefResponse(fullResponse, assetPath);
     }
@@ -470,71 +456,6 @@ function findUnrecognizedScriptSource(assetParts, sources) {
     }
     return undefined;
 }
-/**
- * #624-P3 — opt-in inline graph extraction for `akm show`. Best-effort and
- * timeout-bounded: never throws, never hangs, never mutates the response.
- *
- * Preconditions (caller already checked the flag): a model must be configured
- * (model-available guard via {@link resolveIndexPassExecution}) and the asset
- * must be ungraphed ({@link hasGraphData}). Extraction races a 30s timeout so
- * `show` cannot block on a slow provider; any timeout/error/missing-model path
- * is swallowed and `show` returns its already-assembled response unchanged.
- */
-async function maybeExtractGraphInline(config, sourceStashDir, assetPath) {
-    try {
-        // Resolve readiness and the symbolic runner once. The inline dispatch must
-        // consume this same snapshot even if models.json changes while show runs.
-        const graphExecution = resolveIndexPassExecution("graph", config);
-        if (!graphExecution.runner)
-            return;
-        const emittedNoticeKeys = new Set();
-        const reportNotices = (notices) => {
-            for (const notice of notices) {
-                const key = JSON.stringify(notice);
-                if (emittedNoticeKeys.has(key))
-                    continue;
-                emittedNoticeKeys.add(key);
-                const field = typeof notice.field === "string" ? ` field=${notice.field}` : "";
-                warn(`[akm] lazy graph extraction notice ${notice.code} adapter=${notice.adapter}${field}: ${notice.message}`);
-            }
-        };
-        reportNotices(graphExecution.notices);
-        let alreadyGraphed = false;
-        withIndexDb((db) => {
-            alreadyGraphed = hasGraphData(db, sourceStashDir, assetPath);
-        }, { busyTimeoutMs: TELEMETRY_BUSY_TIMEOUT_MS });
-        if (alreadyGraphed)
-            return;
-        // Open the db for the async extraction ourselves: `withIndexDb` is
-        // synchronous and would close the connection the instant the async fn
-        // returns its Promise (before extraction completes). Close it explicitly
-        // after the race settles instead.
-        const db = openExistingDatabase(resolveStorageLocations().indexDb);
-        let timer;
-        const timeout = new Promise((resolve) => {
-            timer = setTimeout(resolve, 30_000);
-        });
-        try {
-            await Promise.race([
-                extractGraphForSingleFile(db, sourceStashDir, assetPath, {
-                    config,
-                    llmRunner: graphExecution.runner,
-                    onNotices: reportNotices,
-                }),
-                timeout,
-            ]);
-        }
-        finally {
-            if (timer)
-                clearTimeout(timer);
-            closeDatabase(db);
-        }
-    }
-    catch (err) {
-        rethrowIfTestIsolationError(err);
-        // Any other failure: silently return the unchanged show response.
-    }
-}
 /**
  * Minimal `show`: ref → indexer lookup → file contents. Used by callers that
  * just need the raw file (e.g. clone, write-source) and don't want the full

package/dist/commands/sources/bundle-config-ops.js

@@ -93,12 +93,9 @@ export function bundleKeyForUrl(config, url) {
  * (path/url) — the shared {@link deriveBundleId} rule (D-R5), made unique against
  * the currently-configured bundle keys.
  *
- * This helper stays forgiving (no `--name` contract enforcement): it is also
- * used by `akm source add` (`source-manage.ts`'s `addStash`), which predates
- * and is not in scope for the D6 `--name` contract. A caller that DOES need
- * the D6 contract (an illegal or already-taken explicit name failing loudly)
- * validates with {@link validateExplicitBundleName} itself before calling in,
- * as `source-add.ts`'s local/website/registry add paths do.
+ * Every add path validates an explicit `--name` with
+ * {@link validateExplicitBundleName} before calling in (an illegal or taken
+ * name fails loudly), so a `preferredName` that reaches here is returned as is.
  */
 export function nextBundleKey(bundles, preferredName, seedLocator) {
     return deriveBundleId(preferredName, seedLocator, new Set(Object.keys(bundles)));

package/dist/commands/sources/source-manage.js

@@ -3,6 +3,7 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import path from "node:path";
 import { detectAdapterId } from "../../core/adapter/detect-adapter.js";
+import { validateExplicitBundleName } from "../../core/bundle-id.js";
 import { isRemoteUrl } from "../../core/common.js";
 import { bundleEntryToSourceEntry, bundlesToSourceEntries, getSources, mutateConfig } from "../../core/config/config.js";
 import { ConfigError, UsageError } from "../../core/errors.js";
@@ -51,7 +52,10 @@ export function addStash(opts) {
         const bundles = { ...(config.bundles ?? {}) };
         let key;
         if (useDescriptorPath) {
-            if (bundleKeyForUrl(config, target)) {
+            const existingKey = bundleKeyForUrl(config, target);
+            if (name !== undefined)
+                validateExplicitBundleName(bundles, name, existingKey);
+            if (existingKey) {
                 const already = targetIsUrl ? "Source URL already configured" : "Source already configured";
                 result = { sources: getSources(config), added: false, message: already };
                 return config;
@@ -69,7 +73,10 @@ export function addStash(opts) {
         }
         else {
             const resolvedPath = path.resolve(target);
-            if (bundleKeyForPath(config, resolvedPath)) {
+            const existingKey = bundleKeyForPath(config, resolvedPath);
+            if (name !== undefined)
+                validateExplicitBundleName(bundles, name, existingKey);
+            if (existingKey) {
                 result = { sources: getSources(config), added: false, message: "Source path already configured" };
                 return config;
             }