akm-cli 0.9.15 → 0.9.16-alpha.1

package/dist/commands/sources/info.js

@@ -53,15 +53,15 @@ export function assembleInfo(options) {
     // Semantic status is read live from the index's own state, not a cached
     // verdict — a failed embed attempt at search time falls back to FTS and
     // reports that in the search response, it never disables the mode here.
-    const semanticStatus = config.semanticSearchMode === "off"
-        ? "disabled"
-        : !indexStats.hasEmbeddings
-            ? "pending"
-            : indexStats.vecAvailable
-                ? "ready-vec"
-                : "ready-js";
+    // "ready-js" (a JS-computed cosine-similarity fallback for when the
+    // sqlite-vec extension is unavailable) is retired (index redesign, B5):
+    // the units vector store (`units_vec`) is a vec0 virtual table with no
+    // BLOB fallback, so there is nothing to have embeddings without also
+    // having the extension available — `vecAvailable` false and
+    // `hasEmbeddings` true together is no longer a reachable combination.
+    const semanticStatus = config.semanticSearchMode === "off" ? "disabled" : !indexStats.hasEmbeddings ? "pending" : "ready-vec";
     const searchModes = ["fts"];
-    if (semanticStatus === "ready-js" || semanticStatus === "ready-vec") {
+    if (semanticStatus === "ready-vec") {
         searchModes.push("semantic", "hybrid");
     }
     return {

package/dist/commands/sources/installed-stashes.js

@@ -26,7 +26,7 @@ import { beginImmediateTransaction, getStateDbPath, openStateDatabase } from "..
 import { warn } from "../../core/warn.js";
 import { resolveGitContentRoot } from "../../core/write-source.js";
 import { withAssetMutationLease } from "../../indexer/index-writer-lock.js";
-import { akmIndex, runEmbeddingPass } from "../../indexer/indexer.js";
+import { akmIndex, reclassifyIndexDbContention, runEmbeddingPass } from "../../indexer/indexer.js";
 import { compareAndSwapLockfileSnapshot, publishLockfileUpdate, readLockfile, readLockfileForUpdate, } from "../../integrations/lockfile.js";
 import { parseRegistryRef } from "../../registry/resolve.js";
 import { sha256Hex } from "../../runtime.js";
@@ -312,11 +312,15 @@ export async function akmRemove(input) {
             config: {
                 sourceCount: getSources(updatedConfig).length,
             },
+            // `IndexResponse.directoriesScanned`/`directoriesSkipped` were renamed/
+            // removed (#index-redesign W6) — this response's own `index` shape is
+            // unchanged, so bridge from the renamed source field;
+            // `directoriesSkipped` was already always 0.
             index: {
                 mode: index.mode,
                 totalEntries: index.totalEntries,
-                directoriesScanned: index.directoriesScanned,
-                directoriesSkipped: index.directoriesSkipped,
+                directoriesScanned: index.sourcesScanned,
+                directoriesSkipped: 0,
             },
         };
     }
@@ -342,11 +346,15 @@ export async function akmRemove(input) {
         config: {
             sourceCount: getSources(updatedConfig).length,
         },
+        // `IndexResponse.directoriesScanned`/`directoriesSkipped` were renamed/
+        // removed (#index-redesign W6) — this response's own `index` shape is
+        // unchanged, so bridge from the renamed source field;
+        // `directoriesSkipped` was already always 0.
         index: {
             mode: index.mode,
             totalEntries: index.totalEntries,
-            directoriesScanned: index.directoriesScanned,
-            directoriesSkipped: index.directoriesSkipped,
+            directoriesScanned: index.sourcesScanned,
+            directoriesSkipped: 0,
         },
     };
 }
@@ -361,14 +369,13 @@ export async function akmRemove(input) {
 function readCurrentIndexSummary() {
     const db = openReadonlyExistingDatabase(getDbPath());
     if (!db) {
-        return { mode: "incremental", totalEntries: 0, directoriesScanned: 0, directoriesSkipped: 0 };
+        return { mode: "incremental", totalEntries: 0, sourcesScanned: 0 };
     }
     try {
         return {
             mode: "incremental",
             totalEntries: getAllEntries(db).length,
-            directoriesScanned: 0,
-            directoriesSkipped: 0,
+            sourcesScanned: 0,
         };
     }
     finally {
@@ -390,11 +397,15 @@ function buildUpdateResponse(stashDir, target, all, processed, opts) {
         config: {
             sourceCount: getSources(finalConfig).length,
         },
+        // `IndexResponse.directoriesScanned`/`directoriesSkipped` were renamed/
+        // removed (#index-redesign W6) — `UpdateResponse["index"]`'s own shape is
+        // unchanged, so bridge from the renamed source field;
+        // `directoriesSkipped` was already always 0.
         index: {
             mode: index.mode,
             totalEntries: index.totalEntries,
-            directoriesScanned: index.directoriesScanned,
-            directoriesSkipped: index.directoriesSkipped,
+            directoriesScanned: index.sourcesScanned,
+            directoriesSkipped: 0,
             ...(index.scanComplete !== undefined ? { scanComplete: index.scanComplete } : {}),
             // A real embedding pass (`akmIndex`/`runEmbeddingPass`) reports its own
             // verified `semanticStatus`. When no pass ran this update (the
@@ -462,7 +473,9 @@ function openUnifiedUpdateTransaction() {
                 candidate.exec(`ATTACH DATABASE ${sqliteStringLiteral(statePath)} AS "${UPDATE_STATE_SCHEMA}"`);
                 // openIndexDatabase invokes this before ensureSchema, so the outer
                 // transaction begins before the first update-owned index mutation.
-                beginImmediateTransaction(candidate);
+                // `candidate` is the index.db connection, so contention here must
+                // report as INDEX_DB_CONTENDED, not the state.db default.
+                beginImmediateTransaction(candidate, "index");
             },
         });
         return {
@@ -540,7 +553,15 @@ async function runPostCommitEmbeddingPass(index) {
         return { ...index, verification };
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
+        // Run the failure through the same index.db contention classifier the
+        // drain catch uses (indexer.ts's reclassifyIndexDbContention) before
+        // building the message: this catch's first statement, openIndexDatabase
+        // (init runs ensureSchema and writes), can throw the raw SQLite driver
+        // error under contention, and this was the last surviving non-fatal
+        // catch that printed that raw text verbatim to the operator instead of
+        // reporting it as index.db contention.
+        const reportedError = reclassifyIndexDbContention(error);
+        const message = reportedError instanceof Error ? reportedError.message : String(reportedError);
         warn(`[akm bundle update] post-commit embedding pass failed: ${message}`);
         return {
             ...index,

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

@@ -86,8 +86,13 @@ async function addLocalSource(ref, sourcePath, stashDir, explicitName, explicitA
         index: {
             mode: index.mode,
             totalEntries: index.totalEntries,
-            directoriesScanned: index.directoriesScanned,
-            directoriesSkipped: index.directoriesSkipped,
+            // `IndexResponse.directoriesScanned`/`directoriesSkipped` were renamed/
+            // removed (#index-redesign W6: reconcile is a flat per-file stat walk,
+            // never a directory walk) — this response's own `directoriesScanned`/
+            // `directoriesSkipped` shape is unchanged, so bridge from the renamed
+            // source field; `directoriesSkipped` was already always 0.
+            directoriesScanned: index.sourcesScanned,
+            directoriesSkipped: 0,
             ...(index.warnings?.length ? { warnings: index.warnings } : {}),
         },
     };
@@ -151,8 +156,13 @@ async function addWebsiteSource(ref, stashDir, name, options) {
         index: {
             mode: index.mode,
             totalEntries: index.totalEntries,
-            directoriesScanned: index.directoriesScanned,
-            directoriesSkipped: index.directoriesSkipped,
+            // `IndexResponse.directoriesScanned`/`directoriesSkipped` were renamed/
+            // removed (#index-redesign W6: reconcile is a flat per-file stat walk,
+            // never a directory walk) — this response's own `directoriesScanned`/
+            // `directoriesSkipped` shape is unchanged, so bridge from the renamed
+            // source field; `directoriesSkipped` was already always 0.
+            directoriesScanned: index.sourcesScanned,
+            directoriesSkipped: 0,
             ...(index.warnings?.length ? { warnings: index.warnings } : {}),
         },
     };
@@ -238,8 +248,13 @@ async function addRegistryStash(ref, stashDir, writable) {
         index: {
             mode: index.mode,
             totalEntries: index.totalEntries,
-            directoriesScanned: index.directoriesScanned,
-            directoriesSkipped: index.directoriesSkipped,
+            // `IndexResponse.directoriesScanned`/`directoriesSkipped` were renamed/
+            // removed (#index-redesign W6: reconcile is a flat per-file stat walk,
+            // never a directory walk) — this response's own `directoriesScanned`/
+            // `directoriesSkipped` shape is unchanged, so bridge from the renamed
+            // source field; `directoriesSkipped` was already always 0.
+            directoriesScanned: index.sourcesScanned,
+            directoriesSkipped: 0,
             ...(index.warnings?.length ? { warnings: index.warnings } : {}),
         },
     };

package/dist/commands/sources/stash-cli.js

@@ -28,10 +28,9 @@
  * SIGINT/SIGTERM handlers in a try/finally — left byte-for-byte untouched.
  */
 import path from "node:path";
-import { defineCommand } from "citty";
 import * as p from "../../cli/clack.js";
 import { getParsedInvocation } from "../../cli/invocation.js";
-import { defineJsonCommand, GLOBAL_OUTPUT_ARGS, output, parseAllFlagValues, runWithJsonErrors } from "../../cli/shared.js";
+import { defineGroupCommand, defineJsonCommand, GLOBAL_OUTPUT_ARGS, output, parseAllFlagValues, } from "../../cli/shared.js";
 import { assertFlatAssetName } from "../../core/asset/asset-create.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { isHttpUrl, resolveStashDir } from "../../core/common.js";
@@ -40,17 +39,51 @@ import { UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { resolveBundleWriteTarget } from "../../core/mutation-target.js";
 import { getCacheDir } from "../../core/paths.js";
-import { clearLogFile, info, isVerbose, setLogFile } from "../../core/warn.js";
+import { clearLogFile, info, isVerbose, setLogFile, warn } from "../../core/warn.js";
 import { resolveWriteTarget } from "../../core/write-source.js";
-import { releaseIndexRebuildLock, tryAcquireIndexRebuildLock } from "../../indexer/index-rebuild-lock.js";
+import { DRAIN_BATCH_PROGRESS_PREFIX } from "../../indexer/drain.js";
 import { akmIndex } from "../../indexer/indexer.js";
+import { RECONCILE_ROOT_PROGRESS_PREFIX } from "../../indexer/reconcile.js";
 import { getHyphenatedBoolean, getOutputMode } from "../../output/context.js";
 import { inferAssetName, mergeXrefsIntoContent, readKnowledgeInput, resolveSupersedesForWrite, resolveSupersedesWriteTarget, resolveXrefsForWrite, writeMarkdownAsset, } from "../read/knowledge.js";
+import { assembleIndexStatus } from "./index-status.js";
 import { assembleInfo } from "./info.js";
-/** Matches the high-frequency per-committed-batch progress line (#954), excluded from non-verbose JSON-mode stderr. */
-const EMBEDDED_BATCH_PROGRESS_PATTERN = /^Embedded \d+\/\d+ entries\.$/;
-export const indexCommand = defineCommand({
-    meta: { name: "index", description: "Build search index (incremental by default; --full forces full reindex)" },
+/**
+ * The two high-frequency, one-line-per-unit-of-work progress lines (#954) —
+ * drain's per-batch commit line and reconcile's per-root "done" line —
+ * excluded from non-verbose, non-text (JSON/yaml/etc) stderr. Matched by the
+ * exact prefix each producer exports, not a re-derived regex, so the two
+ * never drift apart (index-redesign B5g): this used to be a regex tuned to
+ * the deleted per-entry pipeline's `Embedded N/M entries.` line, which never
+ * matched either replacement line, so every progress line reached stderr
+ * regardless of `--verbose`.
+ */
+function isDetailProgressLine(message) {
+    return message.startsWith(DRAIN_BATCH_PROGRESS_PREFIX) || message.startsWith(RECONCILE_ROOT_PROGRESS_PREFIX);
+}
+export const indexStatusCommand = defineJsonCommand({
+    meta: {
+        name: "status",
+        description: "Show index.db's current state: files, entries, unit coverage, and the last reconcile time.",
+    },
+    run() {
+        output("index-status", assembleIndexStatus());
+    },
+});
+/**
+ * `akm index` = reconcile + drain (docs/plans/index-redesign.md). Still a raw
+ * group command (not `defineJsonCommand`) because its default body owns a
+ * spinner, an AbortController, and SIGINT/SIGTERM handlers in a try/finally;
+ * `defineGroupCommand` gives it `status` as a real subcommand while keeping
+ * that default body as plain `akm index`'s behavior (S-057 canonical
+ * bare-group rule does not apply here — a bare `akm index` has always run the
+ * indexer, and that stays).
+ */
+export const indexCommand = defineGroupCommand({
+    meta: {
+        name: "index",
+        description: "Reconcile the search index and drain the embedding queue (--full forces a full re-derivation)",
+    },
     args: {
         // R-051: `index` is a raw `defineCommand` (not `defineJsonCommand`), so it
         // does not get `GLOBAL_OUTPUT_ARGS` for free. `--format`/`--detail`/
@@ -58,124 +91,99 @@ export const indexCommand = defineCommand({
         // extra positional for a stray value to fall into), so this is purely a
         // `--help` visibility / consistency fix, not a behavior change.
         ...GLOBAL_OUTPUT_ARGS,
-        full: { type: "boolean", description: "Force full reindex", default: false },
-        clean: {
-            type: "boolean",
-            description: "After indexing, remove any entries whose source file no longer exists on disk.",
-            default: false,
-        },
-        "dry-run": {
+        full: {
             type: "boolean",
-            description: "When combined with --clean, report stale entries without deleting them.",
+            description: "Force every file to be re-derived (ignore the unchanged-file shortcut), reconciling in place — " +
+                "existing rows keep their id/embeddings/utility scores; nothing is dropped first.",
             default: false,
         },
         reembed: {
             type: "boolean",
-            description: "Force re-embedding of every entry, bypassing the embedding-model-rename compatibility check.",
+            description: "Drop the active embedding identity's vectors, then re-embed every unit from scratch.",
             default: false,
         },
         "skip-if-locked": {
             type: "boolean",
-            description: "If another `akm index` run already holds the rebuild lock, skip gracefully (exit 0) instead of contending with it. Use for scheduled/opportunistic index runs so they don't pile up against a longer run in progress.",
+            description: "Deprecated, no effect. Index runs no longer take a rebuild lock (docs/plans/index-redesign.md) — " +
+                "every write is a short, idempotent, content-addressed transaction, so two concurrent index runs " +
+                "converge instead of contending. Kept only so existing scripts do not fail on an unknown flag.",
             default: false,
         },
     },
-    async run({ args }) {
-        await runWithJsonErrors(async () => {
-            if (getHyphenatedBoolean(args, "enrich") || getParsedInvocation().getFlagValue("--enrich") !== undefined) {
-                throw new UsageError("`akm index --enrich` has been removed. Plain `akm index` now performs metadata enrichment by default.");
-            }
-            if (getHyphenatedBoolean(args, "re-enrich") || getParsedInvocation().getFlagValue("--re-enrich") !== undefined) {
-                throw new UsageError("`akm index --re-enrich` has been removed. Re-enrichment of index-time LLM passes is not exposed in this slice.");
-            }
-            // #956: opt-in, non-blocking rebuild lock — never gates a human-typed
-            // `akm index` (it only warns and contends), but a scheduled/opportunistic
-            // caller can pass --skip-if-locked to step aside instead of piling up
-            // behind a run already in progress. Acquired before any other side
-            // effect (log file, spinner) so a skip does neither.
-            const lockAcquisition = tryAcquireIndexRebuildLock(args["skip-if-locked"]);
-            if (lockAcquisition.state === "skipped") {
-                output("index", {
-                    ok: true,
-                    skipped: {
-                        reason: "lock-held",
-                        pid: lockAcquisition.holder.pid,
-                        // #956: the launcher pid (when known) alongside the pid that
-                        // actually holds the lock — every process listing and task log
-                        // shows the launcher pid, not the bun/node child's.
-                        launcherPid: lockAcquisition.holder.launcherPid,
-                        startedAt: lockAcquisition.holder.startedAt,
-                    },
-                });
-                return;
-            }
-            const outputMode = getOutputMode();
-            const controller = new AbortController();
-            const abort = () => controller.abort(new Error("index interrupted"));
-            process.once("SIGINT", abort);
-            process.once("SIGTERM", abort);
-            const indexLogFile = path.join(getCacheDir(), "logs", "index", `${new Date().toISOString().replace(/[:.]/g, "-")}.log`);
-            setLogFile(indexLogFile);
-            const verbose = isVerbose();
-            const spin = !verbose && outputMode.format === "text" ? p.spinner() : null;
+    subCommands: { status: indexStatusCommand },
+    async defaultRun({ args }) {
+        if (getHyphenatedBoolean(args, "enrich") || getParsedInvocation().getFlagValue("--enrich") !== undefined) {
+            throw new UsageError("`akm index --enrich` has been removed. Plain `akm index` now performs metadata enrichment by default.");
+        }
+        if (getHyphenatedBoolean(args, "re-enrich") || getParsedInvocation().getFlagValue("--re-enrich") !== undefined) {
+            throw new UsageError("`akm index --re-enrich` has been removed. Re-enrichment of index-time LLM passes is not exposed in this slice.");
+        }
+        if (args["skip-if-locked"]) {
+            warn("[index] --skip-if-locked is deprecated and has no effect — index runs no longer take a rebuild lock.");
+        }
+        const outputMode = getOutputMode();
+        const controller = new AbortController();
+        const abort = () => controller.abort(new Error("index interrupted"));
+        process.once("SIGINT", abort);
+        process.once("SIGTERM", abort);
+        const indexLogFile = path.join(getCacheDir(), "logs", "index", `${new Date().toISOString().replace(/[:.]/g, "-")}.log`);
+        setLogFile(indexLogFile);
+        const verbose = isVerbose();
+        const spin = !verbose && outputMode.format === "text" ? p.spinner() : null;
+        if (spin) {
+            spin.start(`Building search index${args.full ? " (full rebuild)" : ""}...`);
+        }
+        let latestMessage = "";
+        // Resolve the stash dir once at the `akm index` command boundary and
+        // thread it into the indexer (WI-9.10 CLI-wide sweep) — the indexer leaf
+        // no longer reads the ambient `resolveStashDir()`.
+        const stashDir = resolveStashDir();
+        try {
+            const result = await akmIndex({
+                stashDir,
+                full: args.full,
+                reembed: args.reembed,
+                onProgress: ({ phase, message, processed, total }) => {
+                    latestMessage = message;
+                    const progressPrefix = processed !== undefined && total !== undefined ? `[${processed}/${total}] ` : "";
+                    if (verbose) {
+                        info(`[index:${phase}] ${progressPrefix}${message}`);
+                    }
+                    else if (spin) {
+                        spin.stop(`${progressPrefix}${message}`);
+                        spin.start(`${progressPrefix}${message}`);
+                    }
+                    else if (!isDetailProgressLine(message)) {
+                        // Non-verbose, non-text (JSON/yaml/etc) mode: silence used to be
+                        // total until the run finished (#954) — a stalled
+                        // run looked identical to "nothing written". Phase-start
+                        // messages, the credential diagnostic, and the reconcile/drain
+                        // totals now reach stderr here too; the high-frequency
+                        // per-root `Reconciled "…"` and per-batch `[drain] batch N: …`
+                        // lines are deliberately excluded — that would be spam, not a
+                        // heartbeat. `--verbose` (the `if` branch above) still gets
+                        // every one of them.
+                        info(`[index:${phase}] ${progressPrefix}${message}`);
+                    }
+                },
+                signal: controller.signal,
+            });
             if (spin) {
-                spin.start(`Building search index${args.full ? " (full rebuild)" : ""}...`);
-            }
-            let latestMessage = "";
-            // Resolve the stash dir once at the `akm index` command boundary and
-            // thread it into the indexer (WI-9.10 CLI-wide sweep) — the indexer leaf
-            // no longer reads the ambient `resolveStashDir()`.
-            const stashDir = resolveStashDir();
-            try {
-                const result = await akmIndex({
-                    stashDir,
-                    full: args.full,
-                    clean: args.clean,
-                    dryRun: args["dry-run"],
-                    reembed: args.reembed,
-                    onProgress: ({ phase, message, processed, total }) => {
-                        latestMessage = message;
-                        const progressPrefix = processed !== undefined && total !== undefined ? `[${processed}/${total}] ` : "";
-                        if (verbose) {
-                            info(`[index:${phase}] ${progressPrefix}${message}`);
-                        }
-                        else if (spin) {
-                            spin.stop(`${progressPrefix}${message}`);
-                            spin.start(`${progressPrefix}${message}`);
-                        }
-                        else if (!EMBEDDED_BATCH_PROGRESS_PATTERN.test(message)) {
-                            // Non-verbose, non-text (JSON/yaml/etc) mode: silence used to be
-                            // total until the run finished (#954) — a stalled
-                            // run looked identical to "nothing written". Phase-start
-                            // messages and the embedding heartbeat now reach stderr here
-                            // too; the high-frequency per-batch `Embedded N/M entries.`
-                            // line (emitted after every committed batch)
-                            // is deliberately excluded — that would be spam, not a
-                            // heartbeat.
-                            info(`[index:${phase}] ${progressPrefix}${message}`);
-                        }
-                    },
-                    signal: controller.signal,
-                });
-                if (spin) {
-                    spin.stop(`Indexed ${result.totalEntries} assets.`);
-                }
-                output("index", result);
+                spin.stop(`Indexed ${result.totalEntries} assets.`);
             }
-            catch (error) {
-                if (spin) {
-                    spin.stop(latestMessage ? `Indexing failed after: ${latestMessage}` : "Indexing failed.");
-                }
-                throw error;
-            }
-            finally {
-                clearLogFile();
-                process.off("SIGINT", abort);
-                process.off("SIGTERM", abort);
-                if (lockAcquisition.state === "acquired")
-                    releaseIndexRebuildLock(lockAcquisition.ownership);
+            output("index", result);
+        }
+        catch (error) {
+            if (spin) {
+                spin.stop(latestMessage ? `Indexing failed after: ${latestMessage}` : "Indexing failed.");
             }
-        });
+            throw error;
+        }
+        finally {
+            clearLogFile();
+            process.off("SIGINT", abort);
+            process.off("SIGTERM", abort);
+        }
     },
 });
 export const infoCommand = defineJsonCommand({

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

@@ -82,7 +82,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { applyPostContributorFields, applyPreContributorFields, extractPackageMetadata, getMarkdownFragmentContent, hasMarkdownFragmentContent, setMarkdownFragmentContent, } from "../../../indexer/passes/metadata.js";
-import { assetPathCandidatesForName, assetPathForName, deriveCanonicalAssetNameFromStashRoot, placementTypes, stashDirFor, stashDirNames, } from "../../asset/asset-placement.js";
+import { assetPathCandidatesAreOrderedByPreference, assetPathCandidatesForName, assetPathForName, deriveCanonicalAssetNameFromStashRoot, placementTypes, stashDirFor, stashDirNames, } from "../../asset/asset-placement.js";
 import { parseFrontmatter } from "../../asset/frontmatter.js";
 import { executionDefaultsFromFrontmatter, renderMarkdownExecutionSource } from "../execution-source.js";
 import { recognizeMatch } from "../recognize-match.js";
@@ -489,7 +489,25 @@ export const akmAdapter = {
      * type's own stash subdir) and the LOOSE FALLBACK (authored anywhere else
      * in the bundle, so the canonical name is the file's full path relative to
      * the bundle root instead of the stash subdir). `assetPathCandidatesForName`
-     * additionally expands `env`'s `.env`/`<name>.env` duality on each.
+     * additionally expands `env`'s `.env`/`<name>.env` duality, and memory's
+     * `<name>`/`<name>.derived` twin duality, on each.
+     *
+     * `priority` (#882 fix) carries each candidate's rank WITHIN its own root's
+     * list, but ONLY for a type whose duality is a declared, ORDERED
+     * preference per `assetPathCandidatesAreOrderedByPreference` (only
+     * `memory`, today) — `assetPathCandidatesForName` returns primary before
+     * derived-twin for that type, so index 0 is the declared winner when both
+     * exist. CANONICAL and LOOSE are separate lists whose ranks both start
+     * back at 0: two candidates that tie on rank (e.g. the canonical and loose
+     * spellings both being the primary, rank-0, form) are a genuine collision
+     * between two independently-authored files, not a declared preference —
+     * only a rank difference WITHIN one root's own list resolves silently.
+     * Every other type's candidates (including `env`'s `.env`/`default.env`
+     * pair — co-equal spellings, not an ordered preference, per that same
+     * predicate's doc comment) carry NO `priority`, unchanged from before
+     * #882: `resolveAdapterConceptOwner` treats priority-less candidates as
+     * tied, so more than one existing together still collides. See
+     * `AdapterReadCandidate.priority`'s doc comment.
      */
     readCandidates(c, conceptId) {
         const posix = conceptId.replace(/\\/g, "/");
@@ -503,9 +521,23 @@ export const akmAdapter = {
             return [];
         const canonical = assetPathCandidatesForName(type, path.join(c.root, head), rest);
         const loose = assetPathCandidatesForName(type, c.root, rest);
-        return [...new Set([...canonical, ...loose])].map((candidatePath) => ({
+        if (!assetPathCandidatesAreOrderedByPreference(type)) {
+            return [...new Set([...canonical, ...loose])].map((candidatePath) => ({
+                path: candidatePath,
+                conceptId: posix,
+            }));
+        }
+        const priorityByPath = new Map();
+        for (const list of [canonical, loose]) {
+            list.forEach((candidatePath, rank) => {
+                if (!priorityByPath.has(candidatePath))
+                    priorityByPath.set(candidatePath, rank);
+            });
+        }
+        return [...priorityByPath.keys()].map((candidatePath) => ({
             path: candidatePath,
             conceptId: posix,
+            priority: priorityByPath.get(candidatePath),
         }));
     },
     /**

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

@@ -172,7 +172,17 @@ export function foldRecognizedMetadata(rendererName, file) {
                 const fm = parseFrontmatter(file.content()).data;
                 applyFrontmatterDescriptionAndTags(fm, out);
                 const hints = new Set();
-                const source = nonEmptyString(fm.source);
+                // fix-ranking-derived-outranks-primary: `source:` on an ordinary
+                // memory is an author-written citation worth indexing as a hint, but
+                // on an inferred (`.derived`) twin it is ALWAYS the machine-written
+                // provenance backref `memory-inference.ts` writes (`memories/<parent>`
+                // — see its `FM_SOURCE`), already captured properly as
+                // `entry.derivedFrom` (metadata.ts). Folding that backref into
+                // searchHints too means the base memory's own name — almost always a
+                // query token whenever the base is relevant — auto-credits the twin
+                // via `search-hint-ranking`'s substring match, independent of whether
+                // the twin's own content actually matches the query.
+                const source = fm.inferred === true ? undefined : nonEmptyString(fm.source);
                 if (source)
                     hints.add(source);
                 const fmObservedAt = nonEmptyString(fm.observed_at);

package/dist/core/asset/asset-placement.js

@@ -269,3 +269,38 @@ export function assetPathCandidatesForName(assetType, typeRoot, name) {
     const namedForm = path.join(typeRoot, base, "default.env");
     return [...new Set([primary, dotForm, namedForm])];
 }
+/**
+ * Whether {@link assetPathCandidatesForName}'s returned list for `assetType`
+ * is an ORDERED preference — earlier candidates are a declared winner over
+ * later ones, so a physical-owner resolver may pick the earliest that exists
+ * with no throw when more than one does — or a set of CO-EQUAL spellings,
+ * where more than one existing together is a genuine authoring collision to
+ * report, not a preference to resolve silently. #882's fix (the memory
+ * `.derived`-twin bug) needs this distinction: attaching a declared rank to
+ * every multi-candidate type's list turned `env`'s co-equal collision into a
+ * silently-resolved false negative (#882 follow-up) — the two dualities this
+ * module documents are NOT the same kind of thing.
+ *
+ * Only `memory` is ordered. Its own doc comment above states a winner in so
+ * many words: "The plain `.md` file wins when both exist, so it stays
+ * `primary`" — `.derived` is a provenance marker on the SAME identity, not a
+ * second, independently-authored file.
+ *
+ * `env`'s `.env`/`default.env` duality is explicitly NOT ordered — the doc
+ * comment above says only that both spellings "derive the same canonical
+ * name" and a lookup "must consider both", never that one wins over the
+ * other. They are two independently authored files that happen to collide
+ * on one ref; both existing together is exactly the ambiguity
+ * `AdapterConceptCollisionError` exists to report.
+ *
+ * Callers that attach a preference rank to distinguish a declared duality
+ * from a genuine collision (`AdapterReadCandidate.priority`,
+ * `resolveAdapterConceptOwner` in `indexer/lookup/adapter-concept-owner.ts`)
+ * must consult this predicate per asset type rather than assuming every
+ * multi-candidate type behaves like `memory` — and must NOT special-case the
+ * literal `.derived` suffix or `assetType === "memory"` themselves; this is
+ * the one place that knowledge lives.
+ */
+export function assetPathCandidatesAreOrderedByPreference(assetType) {
+    return assetType === "memory";
+}

package/dist/core/config/schema/embedding.js

@@ -33,32 +33,6 @@ export const EmbeddingConnectionConfigSchema = z
     // `akm index` when ensureSchema rejects it (§24.2 "Semantic" gate).
     dimension: positiveInt.max(4096).optional(),
     localModel: z.string().min(1).optional(),
-    /**
-     * Per-document token cap applied BEFORE batching (default 512,
-     * `DEFAULT_MAX_INPUT_TOKENS` in `src/llm/embedders/remote.ts`, #956).
-     * The materializer truncates a document's embedded text to
-     * this cap (head only, unicode-safe) instead of skipping it outright, so
-     * one oversized entry can no longer fail a whole batch. Distinct from
-     * `maxTokens` below, which bounds a whole HTTP REQUEST (many documents);
-     * this bounds one DOCUMENT.
-     */
-    maxInputTokens: positiveInt.optional(),
-    /**
-     * Client-side per-request token budget — how many documents' estimated
-     * tokens fit in one HTTP request (default `DEFAULT_TOKEN_BUDGET` = 6000
-     * in `src/llm/embedders/remote.ts`). With the 512-token `maxInputTokens`
-     * cap above, a request carries about 11 documents by default.
-     */
-    maxTokens: positiveInt.optional(),
-    batchSize: positiveInt.optional(),
-    /**
-     * Ollama's `num_ctx` ONLY (#956) — sent verbatim as
-     * `options.num_ctx` on the native `/api/embed` request. It no longer also
-     * feeds the client-side request token budget (`maxTokens` above): the two
-     * used to share this one field, so setting it for the server's context
-     * window silently changed request batching too.
-     */
-    contextLength: positiveInt.optional(),
     ollamaOptions: EmbeddingOllamaOptionsSchema.optional(),
     /**
      * Per-request timeout in milliseconds for a remote embedding request
@@ -72,10 +46,13 @@ export const EmbeddingConnectionConfigSchema = z
      * Overrides the fixed in-flight request window (#954, added after field
      * evidence from multi-slot local servers). Bounded 1-16. Unset keeps
      * today's default: 1 for a loopback endpoint, 2 for a remote one
-     * (`resolveEmbeddingConcurrency`, `src/llm/embedders/remote.ts`). Set it
-     * only for an endpoint that genuinely serves parallel requests (llama.cpp
-     * `--parallel N`, vLLM) — request SIZE (`batchSize`, `maxTokens`/
-     * `contextLength`) remains the first throughput lever.
+     * (`resolveEmbeddingConcurrency`, `src/llm/embedders/remote.ts`), unless
+     * the provider's own probed slot count overrides it
+     * (`probeProviderLimits`, `src/llm/embedders/provider-limits.ts`, used by
+     * `akm index`'s drain queue). Set it only for an endpoint that genuinely
+     * serves parallel requests (llama.cpp `--parallel N`, vLLM) — request
+     * SIZE, packed against the provider's own probed context window, remains
+     * the first throughput lever.
      */
     concurrency: positiveInt.max(16).optional(),
 })