akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

package/dist/indexer/init.js

@@ -4,35 +4,32 @@
 /**
  * Explicit composition root for the indexer's built-in registrations.
  *
- * Historically two independent lazy gates (`ensureBuiltinsRegistered` in
- * `walk/file-context.ts` and `ensureBuiltinMetadataContributorsRegistered` in
- * `passes/metadata-contributors.ts`) each registered a different built-in set
- * on first use. That implicit, order-dependent wiring is the M1/M2 finding in
- * `docs/technical/code-health-brittleness-audit.md`.
+ * Historically a lazy gate (`ensureBuiltinsRegistered` in `walk/file-context.ts`)
+ * registered the built-in renderer set on first use. That implicit,
+ * order-dependent wiring is the M1/M2 finding in
+ * the 2026-06 code-health brittleness audit.
  *
- * `initIndexer()` folds both into a single deterministic, idempotent entry
- * point. It registers, exactly once:
+ * `initIndexer()` folds the renderer registration into a single deterministic,
+ * idempotent entry point. It registers, exactly once:
  *
- *  1. Built-in matchers   — `registerBuiltinMatchers()` (`walk/matchers.ts`).
- *  2. Built-in renderers  — `registerBuiltinRenderers()` (`output/renderers.ts`).
- *  3. Metadata contributors — top-level registration side-effects that run when
- *     `output/renderers.ts` and `workflows/renderer.ts` are imported.
+ *  1. Built-in renderers — `registerBuiltinRenderers()` (`output/renderers.ts`),
+ *     which value-imports the workflow renderers from `workflows/renderer.ts`.
  *
- * Importing `output/renderers.ts` satisfies both (2) and the renderer-owned
- * metadata contributors; `workflows/renderer.ts` is imported explicitly for the
- * workflow contributor (it is already transitively pulled in by renderers, but
- * the explicit import preserves the original gate's import set and keeps the
- * wiring self-documenting).
+ * Recognition is no longer registry-driven: the chunk-3 cutover replaced the
+ * `registerBuiltinMatchers()`/`runMatchers()` competition with the akm adapter's
+ * synchronous `recognizeMatch()` (`core/adapter/adapters/akm-adapter.ts`), so no
+ * matcher registration happens here. Index-time metadata is likewise no longer
+ * registry-driven: the `akm` adapter's synchronous `foldRecognizedMetadata`
+ * (`core/adapter/adapters/akm-metadata.ts`) computes it inline during recognize.
  *
  * Timing is preserved: this stays a *lazy* gate. It is awaited from the same
- * accessor call sites the old gates were awaited from, so no startup work is
+ * accessor call sites the old gate was awaited from, so no startup work is
  * forced eagerly. The shared promise makes concurrent and repeat calls safe —
  * the registrations run at most once per process.
  */
 let initPromise;
 /**
- * Idempotently register every built-in indexer contributor (matchers,
- * renderers, and metadata contributors).
+ * Idempotently register every built-in indexer renderer.
  *
  * Safe to call repeatedly and concurrently: the registration work runs at most
  * once; subsequent calls await the same resolved promise.
@@ -40,13 +37,9 @@ let initPromise;
 export function initIndexer() {
     if (!initPromise) {
         initPromise = (async () => {
-            const { registerBuiltinMatchers } = await import("./walk/matchers.js");
-            // Importing renderers registers the built-in metadata contributors as a
-            // load-time side-effect and exposes registerBuiltinRenderers().
+            // Importing renderers exposes registerBuiltinRenderers(); it value-imports
+            // the workflow renderers, so no separate workflows/renderer import is needed.
             const { registerBuiltinRenderers } = await import("../output/renderers.js");
-            // Imported for the workflow metadata contributor's load-time side-effect.
-            await import("../workflows/renderer.js");
-            registerBuiltinMatchers();
             registerBuiltinRenderers();
         })();
     }

package/dist/indexer/installations.js

@@ -0,0 +1,142 @@
+// 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/.
+/**
+ * `deriveInstallations` — akm 0.9.0 Chunk 5, milestone M-a.
+ *
+ * Bridges the `SearchSource[]` model (the live indexer's source list,
+ * `search-source.ts`) onto the durable `BundleInstallation[]` /
+ * `BundleComponent[]` model (spec §1.1). LIVE: called from the indexer
+ * (provenance derivation), the proposal repository, and written-asset
+ * indexing. The originally-planned full "Step-3" `scanComponent`-driven scan
+ * swap was superseded by the narrower Chunk-5 F4a drain-dir engine swap; the
+ * shadow-parity scaffolding module (`scan/scan-installations.ts`) was deleted
+ * as dead in the 0.9.0 close-out.
+ *
+ * Per source → one installation:
+ *   - `id`       = `source.registryId` ?? a deterministic slug of `source.path`
+ *                  (the `<bundle>` prefix of every ref this installation emits,
+ *                  spec §1.3). Slugs are made unique WITHIN a derivation batch
+ *                  by appending a short path-hash suffix on collision, so two
+ *                  sources sharing a basename never mint the same bundle id.
+ *   - `trusted`  = `source.writable === true`. 0.9.0 ships no first-class trust
+ *                  record (spec §1.3 — "no new trust machinery"); the writable
+ *                  primary/config stashes are the user's own and count as
+ *                  trusted, read-only registry caches do not. Nothing consumes
+ *                  `trusted` in the live path yet (installation grants nothing,
+ *                  History D8) — this is the Tier-A placeholder mapping.
+ *   - components = ONE component for the current single-root akm layout
+ *                  (spec §1.2 rule 5): `{ id, root: source.path, adapter }`. The
+ *                  akm layout's type dirs (`knowledge/`, `skills/`, …) are NOT
+ *                  separate components — they are type-derived leading path
+ *                  segments of the conceptId within the one component.
+ *
+ * ── The component id == the bundle id (transitional coupling) ──
+ *
+ * The `akm` adapter's `recognize` derives an item's ref prefix from the
+ * component it is handed (`ref = ${c.id}//${conceptId}`, `akm-adapter.ts`), so
+ * for the single-component akm layout the component id MUST equal the
+ * installation/bundle id for refs to be `bundle//conceptId`. This mirrors the
+ * `akm-adapter.test.ts` convention (`component({ id: BUNDLE_ID })`). Splitting
+ * component-provenance from the bundle prefix (recognize learning the bundle
+ * from the installation) is a downstream contract refinement — nothing in the
+ * live path reads `IndexDocument.component` as distinct from `bundle` today.
+ *
+ * ── Adapter selection (spec §1.2 ordered probe) ──
+ *
+ * The adapter is chosen by the ordered `looksLikeRoot` probe over the built-in
+ * adapters (`getAdapters()`), first match wins. The registry is now a STATIC
+ * FROZEN map (normative §12.6) populated at module load, so this probe runs in
+ * production with the full 11-family set — no registration call is required
+ * first. Array order (`BUILTIN_ADAPTERS`) is the probe precedence, most-specific
+ * first, so a `.claude`/dotenv/wiki root is claimed by its tight probe before
+ * the loose `akm` stash-shape probe.
+ *
+ * When NO adapter's probe fires (an empty or not-yet-materialized root), the
+ * fallback is **`akm`** (see {@link FALLBACK_ADAPTER_ID}), preserving workspace
+ * root behavior. Explicit configured ownership always wins over probing.
+ */
+import { isSourceWriteActivated } from "../core/activation-policy.js";
+import { detectAdapterId } from "../core/adapter/detect-adapter.js";
+import { stashDirFor } from "../core/asset/asset-placement.js";
+import { deriveBundleId, deriveBundleIds, slugForPath } from "../core/bundle-id.js";
+export { deriveBundleId, deriveBundleIds, slugForPath };
+/**
+ * The no-probe-match fallback adapter id.
+ *
+ * The status-quo-preserving default from spec §1.2(3):
+ *
+ *  - Behavior discipline (spec line 267): the AKM workspace root's own indexing
+ *    MUST stay classified `akm`. In this transitional model there is no
+ *    depends on either explicit adapter configuration, `akm.looksLikeRoot`
+ *    firing (type dirs / `.stash` present), or this fallback. A genuinely empty
+ *    root fires no probe; `akm` keeps the implicit workspace root correct.
+ *  - Status quo: before the registry was wired, `getAdapters()` was empty in
+ *    production so EVERY source fell back here — this preserves that exact
+ *    fallback value while the probe now genuinely classifies the non-akm shapes.
+ */
+const FALLBACK_ADAPTER_ID = "akm";
+/**
+ * Resolve the adapter id for a component root via the ordered `looksLikeRoot`
+ * probe (spec §1.2), first match wins; falls back to `akm` when no probe fires.
+ */
+export { detectAdapterId } from "../core/adapter/detect-adapter.js";
+/**
+ * Derive the durable `BundleInstallation[]` from the transitional
+ * `SearchSource[]`. Order is preserved (source priority = installation
+ * priority). Bundle ids are unique within the returned batch.
+ */
+export function deriveInstallations(sources) {
+    const ids = deriveBundleIds(sources);
+    const installations = [];
+    for (const [index, source] of sources.entries()) {
+        // D-R5 rule 1: when the source carries its config bundle key (a slug-legal
+        // registryId), that key IS the installation id — equal by construction to
+        // this derivation. A non-slug-legal registryId slugs from the path instead.
+        const id = ids[index];
+        const writable = isSourceWriteActivated(source);
+        const adapter = source.adapterId ?? detectAdapterId(source.path, FALLBACK_ADAPTER_ID);
+        installations.push({
+            id,
+            trusted: writable,
+            components: [
+                {
+                    // Single-component akm layout: the component id == the bundle id so
+                    // the adapter's `ref = ${c.id}//${conceptId}` yields `bundle//…`.
+                    id,
+                    adapter,
+                    root: source.path,
+                    writable,
+                },
+            ],
+        });
+    }
+    return installations;
+}
+/**
+ * Derive the durable `EntryProvenance` for an indexed entry (Chunk-5 flip
+ * §14.4): `conceptId` is the D-R2 qualified `<stash-subdir>/<name>` spelling
+ * (`stashDirFor(type)` prefix; a foreign type with no placement stash-subdir
+ * keeps the bare name), and `item_ref` is `<bundle>//<conceptId>` — the exact
+ * spelling `recognize` emits as `IndexDocument.ref`. Shared by the full-index
+ * diff-persist writer and the write-path `indexWrittenAssets` fast path so both
+ * populate item_ref identically (F4a M-core-2 item 5 — no NULL-item_ref rows).
+ */
+export function deriveEntryProvenance(bundle, type, name, 
+/**
+ * The OWNING adapter's `doc.conceptId`, when the caller has it. Preferred
+ * verbatim over the akm `stashDirFor` re-derivation so a non-akm adapter's
+ * identity (`pages/foo`, snapshot paths, ...) survives into `item_ref`
+ * (D-R3: identity comes from the resolved entry, not a re-derivation).
+ */
+adapterConceptId) {
+    const typeStashDir = stashDirFor(type);
+    const conceptId = adapterConceptId ?? (typeStashDir !== undefined ? `${typeStashDir}/${name}` : name);
+    return {
+        itemRef: `${bundle.bundleId}//${conceptId}`,
+        bundleId: bundle.bundleId,
+        componentId: bundle.componentId,
+        conceptId,
+        adapterId: bundle.adapterId,
+    };
+}

package/dist/indexer/passes/dir-staleness.js

@@ -19,16 +19,24 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { getEntriesByDir, getIndexDirState } from "../db/db.js";
-export function getDirIndexState(db, dirPath, files, builtAtMs) {
+import { getEntriesByDir } from "../../storage/repositories/index-entries-repository.js";
+import { getIndexDirState } from "../../storage/repositories/index-meta-repository.js";
+export function getDirIndexState(db, dirPath, files, builtAtMs, indexVariant = "") {
     const prevEntries = getEntriesByDir(db, dirPath);
-    const fingerprint = computeDirFingerprint(dirPath, files);
+    const fingerprint = computeDirFingerprint(dirPath, files, indexVariant);
     if (prevEntries.length > 0) {
         const staleReason = getDirStaleReason(dirPath, files, prevEntries, builtAtMs);
-        if (!staleReason) {
-            return { stale: false, reason: { kind: "unchanged" }, persistedRowCount: prevEntries.length };
+        if (staleReason)
+            return { stale: true, reason: staleReason, persistedRowCount: prevEntries.length };
+        const cachedState = getIndexDirState(db, dirPath);
+        if (!cachedState || cachedState.fileSetHash !== fingerprint.fileSetHash) {
+            return {
+                stale: true,
+                reason: { kind: "index-context-changed", detail: indexVariant },
+                persistedRowCount: prevEntries.length,
+            };
         }
-        return { stale: true, reason: staleReason, persistedRowCount: prevEntries.length };
+        return { stale: false, reason: { kind: "unchanged" }, persistedRowCount: prevEntries.length };
     }
     const cachedState = getIndexDirState(db, dirPath);
     if (cachedState &&
@@ -46,8 +54,8 @@ export function getDirIndexState(db, dirPath, files, builtAtMs) {
         persistedRowCount: 0,
     };
 }
-export function getCachedZeroRowDirState(db, dirPath, files, builtAtMs, priorDirsChanged) {
-    const state = getDirIndexState(db, dirPath, files, builtAtMs);
+export function getCachedZeroRowDirState(db, dirPath, files, builtAtMs, priorDirsChanged, indexVariant = "") {
+    const state = getDirIndexState(db, dirPath, files, builtAtMs, indexVariant);
     if (state.stale || state.reason.kind !== "cached-zero-row-state")
         return undefined;
     if (!canUseIncrementalSkip(state, priorDirsChanged))
@@ -59,7 +67,7 @@ export function canUseIncrementalSkip(state, priorDirsChanged) {
         state.reason.kind === "cached-zero-row-state" &&
         state.reason.detail === "deduped-zero-row");
 }
-export function computeDirFingerprint(_dirPath, files) {
+export function computeDirFingerprint(_dirPath, files, indexVariant = "") {
     const normalizedFiles = [...new Set(files.map((file) => path.basename(file)))].sort();
     let fileMtimeMaxMs = 0;
     for (const file of files) {
@@ -72,7 +80,7 @@ export function computeDirFingerprint(_dirPath, files) {
         }
     }
     return {
-        fileSetHash: normalizedFiles.join("\0"),
+        fileSetHash: [indexVariant, ...normalizedFiles].join("\0"),
         fileMtimeMaxMs,
     };
 }

package/dist/indexer/passes/memory-inference.js

@@ -19,7 +19,7 @@
  * the parent without re-running the LLM.
  *
  * Disabling — two orthogonal gates:
- *   1. `profiles.improve.default.processes.memoryInference.enabled = false`
+ *   1. The selected strategy sets `processes.memoryInference.enabled = false`
  *      blocks the pass at the feature-flag layer (no network call may ever
  *      issue). Historically the v1 spec §14 gate, superseded by the 0.8.0
  *      profile shape.
@@ -36,9 +36,11 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { parseAssetRef } from "../../core/asset/asset-ref.js";
+import { detectAdapterId } from "../../core/adapter/detect-adapter.js";
 import { assembleAsset } from "../../core/asset/asset-serialize.js";
 import { parseFrontmatter, parseFrontmatterBlock } from "../../core/asset/frontmatter.js";
+import { conceptIdFromTypeName, parseRefInput } from "../../core/asset/resolve-ref.js";
+import { todayIso } from "../../core/common.js";
 import { concurrentMap } from "../../core/concurrent.js";
 import { warn } from "../../core/warn.js";
 import { writeAssetToSource } from "../../core/write-source.js";
@@ -60,7 +62,7 @@ const FM_CAPTURE_MODE = "captureMode";
  *
  * Two orthogonal gates:
  *
- *   1. **Feature gate** — `profiles.improve.default.processes.memoryInference.enabled`
+ *   1. **Feature gate** — the selected strategy's `processes.memoryInference.enabled`
  *      (defaults to `true`). When `false`, no network call may issue regardless
  *      of per-pass settings.
  *   2. **Per-pass gate** — `resolveIndexPassLLM("memory", config)` (which
@@ -72,6 +74,7 @@ const FM_CAPTURE_MODE = "captureMode";
  */
 export async function runMemoryInferencePass(ctx) {
     const { config, sources, signal, db, reEnrich, onProgress, options = {} } = ctx;
+    const invocationOwnsConnection = Object.hasOwn(ctx, "llmConfig");
     const compressMemoryToDerivedMemory = options.compressMemoryToDerivedMemory ?? memoryInfer.compressMemoryToDerivedMemory;
     const result = {
         considered: 0,
@@ -90,20 +93,23 @@ export async function runMemoryInferencePass(ctx) {
     // gate) bubbles up into the pass result.
     const inferTelemetry = {};
     // Gate 1 — feature gate via isProcessEnabled, which reads the 0.8.0 path
-    // (profiles.improve.default.processes.memoryInference.enabled). Defaults to
+    // (selected strategy's processes.memoryInference.enabled). Defaults to
     // enabled when the key is absent.
-    if (!isProcessEnabled("index", "memory_inference", config))
+    if (!invocationOwnsConnection && !isProcessEnabled("index", "memory_inference", config))
         return result;
     // Gate 2 — per-pass opt-out (#208). Returns the resolved llm config or
     // `undefined` when the pass should not run.
-    const llmConfig = resolveIndexPassLLM("memory", config);
+    const llmConfig = Object.hasOwn(ctx, "llmConfig") ? ctx.llmConfig : resolveIndexPassLLM("memory", config);
     if (!llmConfig)
         return result;
+    const featureConfig = invocationOwnsConnection
+        ? { ...config, index: { ...config.index, memory: { ...config.index?.memory, enabled: true } } }
+        : config;
     // The pass only writes to the primary (working) stash. Read-only caches
     // (git, npm, website) are deliberately untouched — writing inferred
     // children there would be clobbered by the next sync().
     const primary = sources[0];
-    if (!primary)
+    if (!primary || (primary.adapterId ?? detectAdapterId(primary.path)) !== "akm")
         return result;
     const pending = collectPendingMemories(primary.path).filter((record) => !options.candidateRefs || options.candidateRefs.has(record.ref));
     result.considered = pending.length;
@@ -173,9 +179,9 @@ export async function runMemoryInferencePass(ctx) {
             retryAttempts += 1;
         };
         const derived = db
-            ? await withLlmCache(db, record.filePath, record.body, reEnrich ?? false, () => compressMemoryToDerivedMemory(llmConfig, record.body, signal, config, (evt) => {
+            ? await withLlmCache(db, record.filePath, record.body, reEnrich ?? false, () => compressMemoryToDerivedMemory(llmConfig, record.body, signal, featureConfig, (evt) => {
                 warn(`[akm] LLM fallback for ${evt.feature}: ${evt.reason}`);
-            }, inferTelemetry, onRetryAttempt), validate, undefined, "", {
+            }, inferTelemetry, onRetryAttempt), validate, undefined, "memory-inference-v2", {
                 onCacheHit: () => {
                     fromCache = true;
                 },
@@ -217,8 +223,8 @@ export async function runMemoryInferencePass(ctx) {
             precheck: false,
         };
     }, 
-    // Default concurrency of 4 for cloud APIs. Set `llm.concurrency: 1`
-    // in config.json for local model servers (LM Studio, Ollama).
+    // Caller-set connection concurrency or 1: `resolveLlmEngineUse` does
+    // not forward `engines.<name>.concurrency`, so config cannot raise this.
     llmConfig.concurrency ?? 1);
     for (let i = 0; i < perRecordResults.length; i++) {
         const res = perRecordResults[i];
@@ -310,7 +316,7 @@ export function collectPendingMemories(stashRoot) {
         out.push({
             filePath,
             stashRoot,
-            ref: `memory:${relName}`,
+            ref: conceptIdFromTypeName("memory", relName),
             data: parsed.data,
             body: parsed.content,
             name: relName,
@@ -370,6 +376,7 @@ async function writeDerivedMemory(parent, derived) {
         kind: "filesystem",
         name: "stash",
         path: parent.stashRoot,
+        adapterId: "akm",
     };
     const writeConfig = {
         type: "filesystem",
@@ -378,7 +385,7 @@ async function writeDerivedMemory(parent, derived) {
         writable: true,
     };
     const childName = `${parent.name}.derived`;
-    const childRefStr = `memory:${childName}`;
+    const childRefStr = `memories/${childName}`;
     if (fs.existsSync(derivedChildPath(parent))) {
         // The derived child appeared on disk after the caller's pre-check (#588)
         // — a rare mid-flight race. Report `childExists` so the caller marks the
@@ -387,7 +394,7 @@ async function writeDerivedMemory(parent, derived) {
     }
     try {
         const content = renderDerivedMemory(parent, derived);
-        const childRef = parseAssetRef(childRefStr);
+        const childRef = parseRefInput(childRefStr);
         await writeAssetToSource(writeTarget, writeConfig, childRef, content);
         return { written: 1, childExists: false };
     }
@@ -403,12 +410,15 @@ function renderDerivedMemory(parent, derived) {
     const fm = {
         [FM_INFERRED]: true,
         [FM_CAPTURE_MODE]: "background",
-        [FM_SOURCE]: parent.ref,
+        // The `source:` backref and internal candidate identity use the same current
+        // `memories/<name>` conceptId spelling.
+        [FM_SOURCE]: conceptIdFromTypeName("memory", parent.name),
         description: derived.description,
         tags: derived.tags,
         searchHints: derived.searchHints,
         title: derived.title,
         derivedFrom: parent.name,
+        updated: todayIso(),
     };
     return assembleAsset(fm, `# ${derived.title.trim()}\n\n${derived.content.trim()}\n`);
 }