akm-cli 0.9.26 → 0.9.27-alpha.2

package/dist/llm/client.js

@@ -222,12 +222,18 @@ async function chatCompletionReal(config, messages, options) {
  * a config/endpoint change can never leave a stale verdict in place.
  */
 const jsonSchemaUnsupportedConnections = new Set();
+/**
+ * The same, for the two thinking-control fields (`chat_template_kwargs` and
+ * `enable_thinking`): a strict hosted API answers 400 `Unknown parameter`.
+ */
+const thinkingControlRejectedConnections = new Set();
 function connectionKey(config) {
     return `${config.endpoint}|${config.model}`;
 }
-/** TEST-ONLY. Clear the in-memory json-schema-support tracker between tests. */
-export function _resetJsonSchemaSupportTrackerForTests() {
+/** TEST-ONLY. Clear the in-memory endpoint-support trackers between tests. */
+export function _resetEndpointSupportTrackersForTests() {
     jsonSchemaUnsupportedConnections.clear();
+    thinkingControlRejectedConnections.clear();
 }
 /**
  * Whether this connection has already been proven, this process, not to
@@ -239,6 +245,24 @@ export function _resetJsonSchemaSupportTrackerForTests() {
 export function isJsonSchemaKnownUnsupported(config) {
     return jsonSchemaUnsupportedConnections.has(connectionKey(config));
 }
+/** Whether a real call this process showed this connection rejects the thinking-control fields (#1045). */
+export function isThinkingControlKnownRejected(config) {
+    return thinkingControlRejectedConnections.has(connectionKey(config));
+}
+/**
+ * Whether `err` is a provider's 4xx (a rate limit is not one) that may be a
+ * verdict on the shape of this request rather than on the request's own content.
+ */
+function isRejectedRequest(err) {
+    return (err instanceof LlmCallError &&
+        err.code === "provider_error" &&
+        typeof err.statusCode === "number" &&
+        err.statusCode >= 400 &&
+        err.statusCode < 500 &&
+        err.statusCode !== 429);
+}
+/** A strict API names the field it does not know: `Unknown parameter: 'chat_template_kwargs'.` */
+const THINKING_FIELD_NAMED = /chat_template_kwargs|enable_thinking/;
 /**
  * A single chat-completion attempt: one HTTP request/response cycle, with an
  * inline fallback-once when a schema was requested and the provider 4xx's
@@ -248,29 +272,35 @@ export function isJsonSchemaKnownUnsupported(config) {
  * `config.supportsJsonSchema === false` is the only thing that skips it,
  * and that is a value a human (or workflow author) set explicitly, not one
  * a probe wrote automatically.
+ *
+ * The thinking-control fields get the same treatment (#1045): a 4xx that
+ * names `chat_template_kwargs` or `enable_thinking` is answered by one retry
+ * without them, which may in turn fall back without the schema.
  */
-async function chatCompletionAttempt(config, messages, options, timeoutMs) {
+async function chatCompletionAttempt(config, messages, options, timeoutMs, includeThinking = (options?.enableThinking ?? config.enableThinking) !== undefined &&
+    !isThinkingControlKnownRejected(config)) {
     const wantsSchema = Boolean(options?.responseSchema) && config.supportsJsonSchema !== false && !isJsonSchemaKnownUnsupported(config);
     try {
-        return await chatCompletionAttemptOnce(config, messages, options, timeoutMs, wantsSchema);
+        return await chatCompletionAttemptOnce(config, messages, options, timeoutMs, wantsSchema, includeThinking);
     }
     catch (err) {
-        if (!wantsSchema ||
-            !(err instanceof LlmCallError) ||
-            err.code !== "provider_error" ||
-            typeof err.statusCode !== "number" ||
-            err.statusCode < 400 ||
-            err.statusCode >= 500 ||
-            err.statusCode === 429) {
+        if (!isRejectedRequest(err))
             throw err;
+        if (includeThinking && THINKING_FIELD_NAMED.test(err.message)) {
+            warnVerbose(`[akm] LLM rejected chat_template_kwargs/enable_thinking (${err.statusCode}); retrying once without them: ${err.message}`);
+            const fallback = await chatCompletionAttempt(config, messages, options, timeoutMs, false);
+            thinkingControlRejectedConnections.add(connectionKey(config));
+            return fallback;
         }
+        if (!wantsSchema)
+            throw err;
         warnVerbose(`[akm] LLM rejected response_format:json_schema (${err.statusCode}); retrying once without it: ${err.message}`);
-        const fallback = await chatCompletionAttemptOnce(config, messages, options, timeoutMs, false);
+        const fallback = await chatCompletionAttemptOnce(config, messages, options, timeoutMs, false, includeThinking);
         jsonSchemaUnsupportedConnections.add(connectionKey(config));
         return fallback;
     }
 }
-async function chatCompletionAttemptOnce(config, messages, options, timeoutMs, includeSchema) {
+async function chatCompletionAttemptOnce(config, messages, options, timeoutMs, includeSchema, includeThinking) {
     if (config.extraParams !== undefined) {
         const issue = validateExtraParams(config.extraParams)[0];
         if (issue)
@@ -309,7 +339,7 @@ async function chatCompletionAttemptOnce(config, messages, options, timeoutMs, i
     // (freellmapi, Bifrost) can drop either one depending on how it was built.
     // Send both whenever thinking is explicitly resolved so the same engine
     // block keeps working across a direct vhost or any gateway in front of it.
-    const resolvedEnableThinking = options?.enableThinking ?? config.enableThinking;
+    const resolvedEnableThinking = includeThinking ? (options?.enableThinking ?? config.enableThinking) : undefined;
     const thinkingParams = resolvedEnableThinking === undefined
         ? {}
         : { chat_template_kwargs: { enable_thinking: resolvedEnableThinking }, enable_thinking: resolvedEnableThinking };

package/dist/llm/memory-infer.js

@@ -46,7 +46,7 @@ const PROMPT_PLACEHOLDERS = new Set([
  * — no more "incomplete derived memory payload from LLM; skipping memory"
  * for shape-only failures.
  */
-const DERIVED_MEMORY_JSON_SCHEMA = {
+export const DERIVED_MEMORY_JSON_SCHEMA = {
     type: "object",
     properties: {
         title: { type: "string", minLength: 1 },

package/dist/scripts/akm-migrate-node.js

@@ -25639,6 +25639,7 @@ var $visitAsync = visit.visitAsync;
 import path7 from "node:path";
 // src/runtime.ts
 import { spawn as nodeSpawn, spawnSync as nodeSpawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { createWriteStream, statfsSync } from "node:fs";
 import { createRequire as createRequire2 } from "node:module";
 import path6 from "node:path";
@@ -26803,6 +26804,9 @@ async function writeResponseToFileCapped(filePath, res, options) {
     reader.releaseLock?.();
   }
 }
+function sha256Hex(data) {
+  return createHash("sha256").update(data).digest("hex");
+}
 function getDirname(importMetaUrl) {
   return path6.dirname(fileURLToPath(importMetaUrl));
 }
@@ -36849,7 +36853,7 @@ function withConfigLock(fn) {
 }
 
 // src/core/config/config-sources.ts
-import { createHash } from "node:crypto";
+import { createHash as createHash2 } from "node:crypto";
 import fs9 from "node:fs";
 import path13 from "node:path";
 function bundleComponentConfig(bundle) {
@@ -36912,7 +36916,7 @@ function filesystemBundleSourceId(contentRoot) {
   });
 }
 function hashBundleSourceIdentity(identity3) {
-  return `sha256:${createHash("sha256").update("akm.bundle-source\x00v1\x00").update(JSON.stringify(identity3)).digest("hex")}`;
+  return `sha256:${createHash2("sha256").update("akm.bundle-source\x00v1\x00").update(JSON.stringify(identity3)).digest("hex")}`;
 }
 function bundleContentRoots(config) {
   const bundles = config.bundles ?? {};
@@ -38374,7 +38378,7 @@ async function tryFetchJson(url, headers) {
 }
 
 // src/sources/providers/provider-utils.ts
-import { createHash as createHash4, randomUUID as randomUUID2 } from "node:crypto";
+import { createHash as createHash5, randomUUID as randomUUID2 } from "node:crypto";
 import fs27 from "node:fs";
 import path34 from "node:path";
 
@@ -38469,7 +38473,7 @@ function countLines(text) {
 }
 
 // src/core/adapter/adapters/shared.ts
-import { createHash as createHash2 } from "node:crypto";
+import { createHash as createHash3 } from "node:crypto";
 
 // src/core/asset/frontmatter-lint.ts
 function checkUnquotedDescriptionColon(frontmatterText) {
@@ -38491,7 +38495,7 @@ function checkUnquotedDescriptionColon(frontmatterText) {
 
 // src/core/adapter/adapters/shared.ts
 function hashContent(content) {
-  return createHash2("sha256").update(content, "utf8").digest("hex");
+  return createHash3("sha256").update(content, "utf8").digest("hex");
 }
 function nonEmptyString2(value) {
   if (typeof value !== "string")
@@ -39674,7 +39678,7 @@ function extractDirTagsFromName(name) {
 }
 
 // src/core/adapter/execution-source.ts
-import { createHash as createHash3 } from "node:crypto";
+import { createHash as createHash4 } from "node:crypto";
 
 // src/execution/source.ts
 var EXECUTION_SOURCE_SCHEMA_VERSION = 1;
@@ -40012,7 +40016,7 @@ function renderMarkdownExecutionSource(input) {
       bundle: identity3.bundle,
       adapter: identity3.adapter,
       file: identity3.file,
-      hash: createHash3("sha256").update(raw, "utf8").digest("hex")
+      hash: createHash4("sha256").update(raw, "utf8").digest("hex")
     },
     ...hasDefaults ? { defaults } : {},
     ...extensions === undefined ? {} : { extensions }
@@ -46567,7 +46571,7 @@ function uniqueSlug() {
 }
 function buildInstallCacheDir(cacheRootDir, source, id, version) {
   const safeId = id.replace(/[^a-zA-Z0-9_.-]+/g, "-").replace(/^-+|-+$/g, "");
-  const identitySuffix = version === "writable" ? `-${createHash4("sha256").update(`${source}:${id}`).digest("hex").slice(0, 12)}` : "";
+  const identitySuffix = version === "writable" ? `-${createHash5("sha256").update(`${source}:${id}`).digest("hex").slice(0, 12)}` : "";
   const slug = `${source}-${safeId}${identitySuffix}`;
   const versionSlug = source === "local" ? uniqueSlug() : version?.replace(/[^a-zA-Z0-9_.-]+/g, "-") ?? uniqueSlug();
   return path34.join(cacheRootDir, slug || source, versionSlug);
@@ -46588,7 +46592,7 @@ async function downloadArchive(url, destination) {
 }
 async function computeFileHash(filePath) {
   const data = fs27.readFileSync(filePath);
-  const hash = createHash4("sha256").update(data).digest("hex");
+  const hash = createHash5("sha256").update(data).digest("hex");
   return `sha256:${hash}`;
 }
 function isDirectory(target) {
@@ -46763,7 +46767,7 @@ function redactUrlUserinfo(text) {
   return text.replace(/\b([A-Za-z][A-Za-z0-9+.-]*:\/\/)([^\s/@]+)@/g, "$1[REDACTED]@");
 }
 // src/sources/providers/git-provider.ts
-import { createHash as createHash5 } from "node:crypto";
+import { createHash as createHash6 } from "node:crypto";
 import fs30 from "node:fs";
 import path36 from "node:path";
 
@@ -46824,7 +46828,7 @@ function resolveGitContentDir(config) {
   throw new ConfigError("git source entry must have either `path` or `url`");
 }
 function getCachePaths(repoUrl, cacheRootOverride) {
-  const key = createHash5("sha256").update(repoUrl).digest("hex").slice(0, 16);
+  const key = createHash6("sha256").update(repoUrl).digest("hex").slice(0, 16);
   const cacheRoot = cacheRootOverride ?? getRegistryIndexCacheDir();
   const rootDir = path36.join(cacheRoot, `git-${key}`);
   return {
@@ -47045,7 +47049,7 @@ import fs33 from "node:fs";
 import path39 from "node:path";
 
 // src/sources/providers/tar-utils.ts
-import { createHash as createHash6 } from "node:crypto";
+import { createHash as createHash7 } from "node:crypto";
 import fs32 from "node:fs";
 import path38 from "node:path";
 function verifyArchiveIntegrity(archivePath, expected, source) {
@@ -47058,7 +47062,7 @@ function verifyArchiveIntegrity(archivePath, expected, source) {
     const dashIndex = expected.indexOf("-");
     const algorithm = expected.slice(0, dashIndex);
     const expectedBase64 = expected.slice(dashIndex + 1);
-    const actualBase64 = createHash6(algorithm).update(fileBuffer).digest("base64");
+    const actualBase64 = createHash7(algorithm).update(fileBuffer).digest("base64");
     if (actualBase64 !== expectedBase64) {
       fs32.unlinkSync(archivePath);
       throw new Error(`Integrity check failed for ${archivePath}: expected ${algorithm} digest ${expectedBase64}, got ${actualBase64}`);
@@ -47066,7 +47070,7 @@ function verifyArchiveIntegrity(archivePath, expected, source) {
     return;
   }
   if (/^[0-9a-f]{40}$/i.test(expected)) {
-    const actualHex = createHash6("sha1").update(fileBuffer).digest("hex");
+    const actualHex = createHash7("sha1").update(fileBuffer).digest("hex");
     if (actualHex.toLowerCase() !== expected.toLowerCase()) {
       fs32.unlinkSync(archivePath);
       throw new Error(`Integrity check failed for ${archivePath}: expected sha1 ${expected}, got ${actualHex}`);
@@ -51669,14 +51673,15 @@ class ClaudeHarness extends BaseHarness {
 }
 
 // src/integrations/harnesses/codex/agent-builder.ts
-import { mkdtempSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { mkdirSync } from "node:fs";
 import { join } from "node:path";
 function writeCodexOutputSchemaFile(schema) {
-  const dir = mkdtempSync(join(tmpdir(), "akm-codex-schema-"));
-  const file = join(dir, "output-schema.json");
-  writeFileSync(file, `${JSON.stringify(schema, null, 2)}
-`, "utf8");
+  const text = `${JSON.stringify(schema, null, 2)}
+`;
+  const dir = join(getCacheDir(), "codex-output-schemas");
+  mkdirSync(dir, { recursive: true });
+  const file = join(dir, `${sha256Hex(text)}.json`);
+  writeFileAtomic(file, text);
   return file;
 }
 function ensureSandboxFlags(base) {

package/dist/scripts/akm-migrate.js

@@ -24967,6 +24967,7 @@ var $visitAsync = visit.visitAsync;
 import path7 from "path";
 // src/runtime.ts
 import { spawn as nodeSpawn, spawnSync as nodeSpawnSync } from "child_process";
+import { createHash } from "crypto";
 import { createWriteStream, statfsSync } from "fs";
 import { createRequire } from "module";
 import path6 from "path";
@@ -26131,6 +26132,9 @@ async function writeResponseToFileCapped(filePath, res, options) {
     reader.releaseLock?.();
   }
 }
+function sha256Hex(data) {
+  return createHash("sha256").update(data).digest("hex");
+}
 function getDirname(importMetaUrl) {
   return path6.dirname(fileURLToPath(importMetaUrl));
 }
@@ -36177,7 +36181,7 @@ function withConfigLock(fn) {
 }
 
 // src/core/config/config-sources.ts
-import { createHash } from "crypto";
+import { createHash as createHash2 } from "crypto";
 import fs9 from "fs";
 import path13 from "path";
 function bundleComponentConfig(bundle) {
@@ -36240,7 +36244,7 @@ function filesystemBundleSourceId(contentRoot) {
   });
 }
 function hashBundleSourceIdentity(identity3) {
-  return `sha256:${createHash("sha256").update("akm.bundle-source\x00v1\x00").update(JSON.stringify(identity3)).digest("hex")}`;
+  return `sha256:${createHash2("sha256").update("akm.bundle-source\x00v1\x00").update(JSON.stringify(identity3)).digest("hex")}`;
 }
 function bundleContentRoots(config) {
   const bundles = config.bundles ?? {};
@@ -37702,7 +37706,7 @@ async function tryFetchJson(url, headers) {
 }
 
 // src/sources/providers/provider-utils.ts
-import { createHash as createHash4, randomUUID as randomUUID2 } from "crypto";
+import { createHash as createHash5, randomUUID as randomUUID2 } from "crypto";
 import fs27 from "fs";
 import path34 from "path";
 
@@ -37797,7 +37801,7 @@ function countLines(text) {
 }
 
 // src/core/adapter/adapters/shared.ts
-import { createHash as createHash2 } from "crypto";
+import { createHash as createHash3 } from "crypto";
 
 // src/core/asset/frontmatter-lint.ts
 function checkUnquotedDescriptionColon(frontmatterText) {
@@ -37819,7 +37823,7 @@ function checkUnquotedDescriptionColon(frontmatterText) {
 
 // src/core/adapter/adapters/shared.ts
 function hashContent(content) {
-  return createHash2("sha256").update(content, "utf8").digest("hex");
+  return createHash3("sha256").update(content, "utf8").digest("hex");
 }
 function nonEmptyString2(value) {
   if (typeof value !== "string")
@@ -39002,7 +39006,7 @@ function extractDirTagsFromName(name) {
 }
 
 // src/core/adapter/execution-source.ts
-import { createHash as createHash3 } from "crypto";
+import { createHash as createHash4 } from "crypto";
 
 // src/execution/source.ts
 var EXECUTION_SOURCE_SCHEMA_VERSION = 1;
@@ -39340,7 +39344,7 @@ function renderMarkdownExecutionSource(input) {
       bundle: identity3.bundle,
       adapter: identity3.adapter,
       file: identity3.file,
-      hash: createHash3("sha256").update(raw, "utf8").digest("hex")
+      hash: createHash4("sha256").update(raw, "utf8").digest("hex")
     },
     ...hasDefaults ? { defaults } : {},
     ...extensions === undefined ? {} : { extensions }
@@ -45895,7 +45899,7 @@ function uniqueSlug() {
 }
 function buildInstallCacheDir(cacheRootDir, source, id, version) {
   const safeId = id.replace(/[^a-zA-Z0-9_.-]+/g, "-").replace(/^-+|-+$/g, "");
-  const identitySuffix = version === "writable" ? `-${createHash4("sha256").update(`${source}:${id}`).digest("hex").slice(0, 12)}` : "";
+  const identitySuffix = version === "writable" ? `-${createHash5("sha256").update(`${source}:${id}`).digest("hex").slice(0, 12)}` : "";
   const slug = `${source}-${safeId}${identitySuffix}`;
   const versionSlug = source === "local" ? uniqueSlug() : version?.replace(/[^a-zA-Z0-9_.-]+/g, "-") ?? uniqueSlug();
   return path34.join(cacheRootDir, slug || source, versionSlug);
@@ -45916,7 +45920,7 @@ async function downloadArchive(url, destination) {
 }
 async function computeFileHash(filePath) {
   const data = fs27.readFileSync(filePath);
-  const hash = createHash4("sha256").update(data).digest("hex");
+  const hash = createHash5("sha256").update(data).digest("hex");
   return `sha256:${hash}`;
 }
 function isDirectory(target) {
@@ -46091,7 +46095,7 @@ function redactUrlUserinfo(text) {
   return text.replace(/\b([A-Za-z][A-Za-z0-9+.-]*:\/\/)([^\s/@]+)@/g, "$1[REDACTED]@");
 }
 // src/sources/providers/git-provider.ts
-import { createHash as createHash5 } from "crypto";
+import { createHash as createHash6 } from "crypto";
 import fs30 from "fs";
 import path36 from "path";
 
@@ -46152,7 +46156,7 @@ function resolveGitContentDir(config) {
   throw new ConfigError("git source entry must have either `path` or `url`");
 }
 function getCachePaths(repoUrl, cacheRootOverride) {
-  const key = createHash5("sha256").update(repoUrl).digest("hex").slice(0, 16);
+  const key = createHash6("sha256").update(repoUrl).digest("hex").slice(0, 16);
   const cacheRoot = cacheRootOverride ?? getRegistryIndexCacheDir();
   const rootDir = path36.join(cacheRoot, `git-${key}`);
   return {
@@ -46373,7 +46377,7 @@ import fs33 from "fs";
 import path39 from "path";
 
 // src/sources/providers/tar-utils.ts
-import { createHash as createHash6 } from "crypto";
+import { createHash as createHash7 } from "crypto";
 import fs32 from "fs";
 import path38 from "path";
 function verifyArchiveIntegrity(archivePath, expected, source) {
@@ -46386,7 +46390,7 @@ function verifyArchiveIntegrity(archivePath, expected, source) {
     const dashIndex = expected.indexOf("-");
     const algorithm = expected.slice(0, dashIndex);
     const expectedBase64 = expected.slice(dashIndex + 1);
-    const actualBase64 = createHash6(algorithm).update(fileBuffer).digest("base64");
+    const actualBase64 = createHash7(algorithm).update(fileBuffer).digest("base64");
     if (actualBase64 !== expectedBase64) {
       fs32.unlinkSync(archivePath);
       throw new Error(`Integrity check failed for ${archivePath}: expected ${algorithm} digest ${expectedBase64}, got ${actualBase64}`);
@@ -46394,7 +46398,7 @@ function verifyArchiveIntegrity(archivePath, expected, source) {
     return;
   }
   if (/^[0-9a-f]{40}$/i.test(expected)) {
-    const actualHex = createHash6("sha1").update(fileBuffer).digest("hex");
+    const actualHex = createHash7("sha1").update(fileBuffer).digest("hex");
     if (actualHex.toLowerCase() !== expected.toLowerCase()) {
       fs32.unlinkSync(archivePath);
       throw new Error(`Integrity check failed for ${archivePath}: expected sha1 ${expected}, got ${actualHex}`);
@@ -51664,14 +51668,15 @@ class ClaudeHarness extends BaseHarness {
 }
 
 // src/integrations/harnesses/codex/agent-builder.ts
-import { mkdtempSync, writeFileSync } from "fs";
-import { tmpdir } from "os";
+import { mkdirSync } from "fs";
 import { join as join2 } from "path";
 function writeCodexOutputSchemaFile(schema) {
-  const dir = mkdtempSync(join2(tmpdir(), "akm-codex-schema-"));
-  const file = join2(dir, "output-schema.json");
-  writeFileSync(file, `${JSON.stringify(schema, null, 2)}
-`, "utf8");
+  const text = `${JSON.stringify(schema, null, 2)}
+`;
+  const dir = join2(getCacheDir(), "codex-output-schemas");
+  mkdirSync(dir, { recursive: true });
+  const file = join2(dir, `${sha256Hex(text)}.json`);
+  writeFileAtomic(file, text);
   return file;
 }
 function ensureSandboxFlags(base) {

package/dist/storage/repositories/improve-ledger-repository.js

@@ -50,11 +50,14 @@ export const CONSOLIDATE_LEDGER_SOURCE = "consolidate";
  * promotion is a verdict on that memory's text; asking the model about the
  * same text again can only reproduce the proposal (accepted used to be
  * eligible at once, rejected after 7 days), so the memory waits for an edit.
+ * So does a memory the model judged and left alone (`judged_no_action`):
+ * the same text would be judged weekly with the same answer.
  * The clock stays for a row with no recorded hash — one decided before the
  * hash was recorded — see {@link nextEligibleAt} and {@link isContentDrivenRow}.
  */
 export function isContentDrivenDecision(source, outcome) {
-    return source === CONSOLIDATE_LEDGER_SOURCE && (outcome === "accepted" || outcome === "rejected");
+    return (source === CONSOLIDATE_LEDGER_SOURCE &&
+        (outcome === "accepted" || outcome === "rejected" || outcome === "judged_no_action"));
 }
 /**
  * Whether this row is held by its content hash: a decided consolidate

package/dist/storage/repositories/index-entry-schema.js

@@ -120,20 +120,36 @@ const REQUIRED_ENTRY_COLUMNS = [
     "document_json",
     "derived_from",
 ];
+/**
+ * The transitional columns layout 20 and earlier kept beside the current ones
+ * and layout 21 removed (`entry_key` was the key). They are NOT NULL, so a
+ * table that still has one takes none of this release's inserts, and its
+ * `document_json` is empty (the entry sat in `entry_json`), so none of its rows
+ * can be read either. A 0.9.1 index is such a table.
+ */
+const RETIRED_ENTRY_COLUMNS = ["entry_key", "dir_path", "stash_dir", "entry_json", "entry_type"];
+function entryColumnNames(db) {
+    return new Set(db.prepare("PRAGMA table_info(entries)").all().map((c) => c.name));
+}
 /** Required `entries` columns the table lacks; every column when there is no `entries` table. */
 export function missingEntryColumns(db) {
-    const present = new Set(db.prepare("PRAGMA table_info(entries)").all().map((c) => c.name));
+    const present = entryColumnNames(db);
     return REQUIRED_ENTRY_COLUMNS.filter((column) => !present.has(column));
 }
+/** Retired `entries` columns the table still has: it was written by layout 20 or earlier. */
+export function retiredEntryColumns(db) {
+    const present = entryColumnNames(db);
+    return RETIRED_ENTRY_COLUMNS.filter((column) => present.has(column));
+}
 /**
  * Whether an index database has an `entries` table this release can read. A
  * fresh or empty file has none; an index older than layout 21 has one keyed
- * by columns this release no longer reads, and serves nothing until the next
- * `akm index` recreates it.
+ * by columns this release no longer reads (or lacks the ones it does), and
+ * serves nothing until the next `akm index` recreates it.
  */
 export function hasCurrentEntriesTable(db) {
     try {
-        return missingEntryColumns(db).length === 0;
+        return missingEntryColumns(db).length === 0 && retiredEntryColumns(db).length === 0;
     }
     catch {
         return false;

package/dist/storage/repositories/index-fts-repository.js

@@ -19,9 +19,27 @@ import { splitMarkdownFragments } from "../../core/asset/markdown-fragments.js";
 import { warn } from "../../core/warn.js";
 import { ftsOrMatch, ftsQueryTokens } from "../../indexer/search/fts-query.js";
 import { buildSearchFields } from "../../indexer/search/search-fields.js";
+import { isContentlessFtsDdl, readTableSql } from "./index-entry-schema.js";
+import { deleteMeta, getMeta } from "./index-meta-repository.js";
 import { SQLITE_CHUNK_SIZE } from "./index-sql.js";
 // `entries_fts.rowid = entries.id`, so a per-entry delete is a rowid lookup.
 const INSERT_FTS_SQL = "INSERT INTO entries_fts (rowid, entry_id, name, description, tags, hints, content) VALUES (?, ?, ?, ?, ?, ?, ?)";
+/**
+ * `index_meta` key stamped when a delete took a row out of `entries_fts`.
+ *
+ * FTS5 cannot take a deleted row out of a contentless table's BM25 totals (its
+ * row count, and the token counts the average document length comes from), so
+ * every removal or replacement leaves them one row too high and an updated
+ * index scores differently from a fresh one (#1048). SQLite has no command that
+ * recomputes them (`delete` and `rebuild` are refused on a contentless table),
+ * so the next `akm index` rebuilds the table from `entries`
+ * ({@link rebuildFtsIfTotalsStale}).
+ */
+const FTS_TOTALS_STALE_META = "ftsTotalsStale";
+/** The content-bearing table older SQLite gets subtracts a deleted row itself. */
+function isContentlessFts(db) {
+    return isContentlessFtsDdl(readTableSql(db, "entries_fts"));
+}
 const ftsMutationStatementsByDb = new WeakMap();
 function getFtsMutationStatements(db) {
     const existing = ftsMutationStatementsByDb.get(db);
@@ -29,6 +47,7 @@ function getFtsMutationStatements(db) {
         return existing;
     const statements = {
         deleteOne: db.prepare("DELETE FROM entries_fts WHERE rowid = ?"),
+        markTotalsStale: db.prepare(`INSERT OR IGNORE INTO index_meta (key, value) VALUES ('${FTS_TOTALS_STALE_META}', '1')`),
         insert: db.prepare(INSERT_FTS_SQL),
         upsertFragmentSource: db.prepare("INSERT INTO entry_fragments (entry_id, safe_markdown) VALUES (?, ?) ON CONFLICT(entry_id) DO UPDATE SET safe_markdown = excluded.safe_markdown"),
         deleteFragmentSource: db.prepare("DELETE FROM entry_fragments WHERE entry_id = ?"),
@@ -36,6 +55,11 @@ function getFtsMutationStatements(db) {
     ftsMutationStatementsByDb.set(db, statements);
     return statements;
 }
+/** A delete that removed a row leaves the table's BM25 totals too high until it is rebuilt. */
+function noteRemoval(statements, removed) {
+    if (removed.changes > 0)
+        statements.markTotalsStale.run();
+}
 /**
  * Replace one entry's derived FTS row, and its fragment source when the scan
  * read Markdown, inside the caller's transaction.
@@ -43,7 +67,7 @@ function getFtsMutationStatements(db) {
 export function replaceFtsEntry(db, entryId, entry, fragmentContent) {
     const fields = buildSearchFields(entry);
     const statements = getFtsMutationStatements(db);
-    statements.deleteOne.run(entryId);
+    noteRemoval(statements, statements.deleteOne.run(entryId));
     statements.insert.run(entryId, entryId, fields.name, fields.description, fields.tags, fields.hints, fields.content);
     if (fragmentContent === undefined) {
         // Metadata-only re-upserts and re-keys deserialize the public document
@@ -61,7 +85,7 @@ export function deleteFtsEntries(db, entryIds) {
     for (let i = 0; i < entryIds.length; i += SQLITE_CHUNK_SIZE) {
         const chunk = entryIds.slice(i, i + SQLITE_CHUNK_SIZE);
         const placeholders = chunk.map(() => "?").join(",");
-        db.prepare(`DELETE FROM entries_fts WHERE rowid IN (${placeholders})`).run(...chunk);
+        noteRemoval(getFtsMutationStatements(db), db.prepare(`DELETE FROM entries_fts WHERE rowid IN (${placeholders})`).run(...chunk));
         db.prepare(`DELETE FROM entry_fragments WHERE entry_id IN (${placeholders})`).run(...chunk);
     }
 }
@@ -143,7 +167,9 @@ function materializeIndexedMarkdownFragment(fragment, fragments, parentChars) {
  */
 export function rebuildFts(db) {
     db.transaction(() => {
-        db.exec("DELETE FROM entries_fts");
+        // `delete-all` also resets the BM25 totals, which a plain DELETE leaves as they were (#1048).
+        db.exec(isContentlessFts(db) ? "INSERT INTO entries_fts(entries_fts) VALUES('delete-all')" : "DELETE FROM entries_fts");
+        deleteMeta(db, FTS_TOTALS_STALE_META);
         // Keyset pages, so a large index is never held in memory at once.
         const page = db.prepare("SELECT id, document_json FROM entries WHERE id > ? ORDER BY id LIMIT 500");
         const insertStmt = db.prepare(INSERT_FTS_SQL);
@@ -171,3 +197,18 @@ export function rebuildFts(db) {
         }
     })();
 }
+/**
+ * Rebuild `entries_fts` from `entries` when rows have left it since its BM25
+ * totals were last taken (#1048): about a second at 25,000 entries. Returns
+ * whether it did.
+ */
+export function rebuildFtsIfTotalsStale(db) {
+    if (getMeta(db, FTS_TOTALS_STALE_META) === undefined)
+        return false;
+    if (!isContentlessFts(db)) {
+        deleteMeta(db, FTS_TOTALS_STALE_META);
+        return false;
+    }
+    rebuildFts(db);
+    return true;
+}

package/dist/storage/repositories/index-schema.js

@@ -25,7 +25,7 @@ import path from "node:path";
 import { ConfigError } from "../../core/errors.js";
 import { warn } from "../../core/warn.js";
 import { sha256Hex } from "../../runtime.js";
-import { CANONICAL_ENTRY_SCHEMA_SQL, CANONICAL_INDEX_DB_VERSION, entriesFtsDdl, isContentlessFtsDdl, missingEntryColumns, readTableSql, supportsContentlessDelete, tableExists, } from "./index-entry-schema.js";
+import { CANONICAL_ENTRY_SCHEMA_SQL, CANONICAL_INDEX_DB_VERSION, entriesFtsDdl, isContentlessFtsDdl, missingEntryColumns, readTableSql, retiredEntryColumns, supportsContentlessDelete, tableExists, } from "./index-entry-schema.js";
 import { rebuildFts } from "./index-fts-repository.js";
 import { rebuildAllEntryLinks } from "./index-links-repository.js";
 import { getMeta, setMeta } from "./index-meta-repository.js";
@@ -67,11 +67,13 @@ const REGISTRY_INDEX_CACHE_DDL = `
     ON registry_index_cache(fetched_at);
 `;
 /**
- * An `entries` table missing a required column cannot be read or written by
- * this release (the last such change was v20→v21, which removed the
- * transitional `entry_key`/`dir_path`/... columns and made `item_ref` the
- * key). Recreate only the tables keyed by `entries.id` — their ids are about
- * to be re-minted, so the rows would dangle anyway. The LLM enrichment cache
+ * An `entries` table missing a required column, or still carrying a retired
+ * one, cannot be read or written by this release (the last such change was
+ * v20→v21, which removed the transitional `entry_key`/`dir_path`/... columns
+ * and made `item_ref` the key). Layouts 18–20 carried the current columns
+ * beside the retired ones, so only the retired ones give them away.
+ * Recreate only the tables keyed by `entries.id` — their ids are about to be
+ * re-minted, so the rows would dangle anyway. The LLM enrichment cache
  * (keyed by ref) is kept. The LLM entity-graph tables are unconditionally
  * dropped elsewhere in this file regardless of this recreation (retired
  * 0.9.17-alpha.9), not kept. The next index run re-walks every source.
@@ -80,9 +82,13 @@ function ensureEntriesLayout(db) {
     if (!tableExists(db, "entries"))
         return;
     const missing = missingEntryColumns(db);
-    if (missing.length === 0)
+    const retired = retiredEntryColumns(db);
+    if (missing.length === 0 && retired.length === 0)
         return;
-    warn(`Index database entries table predates the ${missing.join(", ")} column${missing.length === 1 ? "" : "s"} — ` +
+    const why = missing.length > 0
+        ? `predates the ${missing.join(", ")} column${missing.length === 1 ? "" : "s"}`
+        : `still has the retired ${retired.join(", ")} column${retired.length === 1 ? "" : "s"}`;
+    warn(`Index database entries table ${why} — ` +
         "recreating the entries-keyed tables (entries, full-text, embeddings, utility scores); the " +
         "LLM enrichment cache is kept. The next index run re-walks every source.");
     db.transaction(() => {

package/docs/README.md

@@ -49,7 +49,6 @@ Working on akm itself, not just using it.
 
 - [Maintainer Docs](https://github.com/itlackey/akm/blob/main/docs/maintainers/README.md) -- Start here: local development, measuring improvement, and the curate contract
 - [Local Development](https://github.com/itlackey/akm/blob/main/docs/maintainers/local-development.md) -- Dogfooding akm while editing its own source
-- [akm-eval](https://github.com/itlackey/akm/blob/main/docs/maintainers/eval.md) -- Standalone toolkit for measuring whether `akm improve` is working
 - [Curate Workmap](https://github.com/itlackey/akm/blob/main/docs/maintainers/curate-workmap.md) -- The current `akm curate` contract and the highest-value next fixes
 
 ## Look up details
@@ -100,7 +99,7 @@ Source articles for the dev.to publishing pipeline (historical record). See
 - [itlackey/akm-registry](https://github.com/itlackey/akm-registry) -- the official registry index that powers built-in discovery
 - [itlackey/akm-plugins](https://github.com/itlackey/akm-plugins) -- optional integrations for tools like OpenCode
 - [itlackey/akm-bench](https://github.com/itlackey/akm-bench) -- the standalone benchmark harness for measuring agent performance with akm
-- [itlackey/akm-eval](https://github.com/itlackey/akm-eval) -- the eval framework and tools for akm asset quality (distinct from the in-repo [`scripts/akm-eval/` toolkit](https://github.com/itlackey/akm/blob/main/docs/maintainers/eval.md))
+- [itlackey/akm-eval](https://github.com/itlackey/akm-eval) -- the eval framework and tools for akm asset quality
 
 ---