akm-cli 0.9.16 → 0.9.17-alpha.10

package/dist/core/config/config.js

@@ -5,15 +5,16 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { isDeepStrictEqual } from "node:util";
-import { isBundleSlug } from "../asset/asset-ref.js";
-import { isRecord } from "../common.js";
+import { isBundleSlug, parseBundleRef } from "../asset/asset-ref.js";
+import { deriveBundleId } from "../bundle-id.js";
+import { isRecord, resolveStashDir } from "../common.js";
 import { ConfigError } from "../errors.js";
 import { liftLegacyEngineExtraParams } from "../extra-params.js";
 import { formatRegistryLabel, hasRegistryUrlCredentials } from "../registry-url.js";
 import { acquireConfigLock, backupExistingConfig, parseConfigText, readConfigText, withConfigLock, writeConfigAtomic, } from "./config-io.js";
-import { AkmConfigSchema, CURRENT_CONFIG_VERSION, listTopLevelConfigKeys } from "./config-schema.js";
-import { bundleComponentConfig, bundleContentRoot, bundleContentRoots, bundlesToSourceEntries } from "./config-sources.js";
-import { upgradeConfigVersion } from "./config-version-shim.js";
+import { AkmConfigSchema, CURRENT_CONFIG_VERSION } from "./config-schema.js";
+import { bundleComponentConfig, bundleContentRoot, bundleContentRoots, bundleSourceId, bundlesToSourceEntries, filesystemBundleSourceId, isBundleEnabled, } from "./config-sources.js";
+import { resolveSchemaAt } from "./config-walker.js";
 import { deepMergeConfig, isPlainObject } from "./deep-merge.js";
 import { migrateLegacySourceShape } from "./legacy-source-shape-shim.js";
 import { isApiKeyReference, SECRET_STORE_REFERENCE_PATTERN } from "./schema/primitives.js";
@@ -26,36 +27,6 @@ export { VALID_HARNESS_IDS } from "./config-types.js";
 // Canonical taxonomy lives in the schema/validator layer; re-exported here so
 // existing `../core/config/config` import sites keep working.
 export { FEEDBACK_FAILURE_MODES } from "./config-schema.js";
-/**
- * Default value for {@link IndexPassConfig.graphExtractionBatchSize}. Chosen
- * empirically: 4 amortises the per-call HTTP overhead 4× while keeping the
- * combined prompt size well under common 8K/16K context windows (each body is
- * sliced to ~500 chars in the graph-extract prompt builder).
- */
-export const DEFAULT_GRAPH_EXTRACTION_BATCH_SIZE = 4;
-/**
- * Approximate character budget per asset body inside a batched
- * graph-extraction prompt — used by {@link resolveBatchSize} to derive a
- * context-window ceiling when `llm.contextLength` is configured. This accounts
- * for the actual `MAX_BODY_CHARS` (500) in graph-extract.ts plus the system
- * prompt, user prompt wrapper, and expected JSON response overhead.
- */
-const GRAPH_EXTRACTION_CHARS_PER_BODY = 1500;
-/**
- * Clamp a configured batch size against the model's known context window.
- *
- * `configured` defaults to {@link DEFAULT_GRAPH_EXTRACTION_BATCH_SIZE} when
- * `undefined`. When `contextLength` is provided, the result is the smaller of
- * `configured` and `floor(contextLength / GRAPH_EXTRACTION_CHARS_PER_BODY)`,
- * with a floor of 1 so the batched path always processes at least one body.
- */
-export function resolveBatchSize(configured, contextLength) {
-    const base = configured && configured > 0 ? configured : DEFAULT_GRAPH_EXTRACTION_BATCH_SIZE;
-    if (!contextLength || contextLength <= 0)
-        return base;
-    const ceiling = Math.max(1, Math.floor(contextLength / GRAPH_EXTRACTION_CHARS_PER_BODY));
-    return Math.max(1, Math.min(base, ceiling));
-}
 // ── Defaults ────────────────────────────────────────────────────────────────
 export const DEFAULT_CONFIG = {
     configVersion: "0.9.0",
@@ -124,39 +95,39 @@ export function loadUserConfig() {
     };
     return finalConfig;
 }
-/**
- * Acquire the existing config-write sentinel and read a fresh validated
- * generation while keeping the sentinel held. Source update uses this to
- * fence an audited bundle descriptor through publication: a cooperating
- * config writer can commit either before this snapshot or after the update,
- * never between the final generation check and index commit.
- */
-export function acquireConfigReadFence() {
-    const release = acquireConfigLock();
-    try {
-        cachedConfig = undefined;
-        return { config: loadUserConfig(), release };
-    }
-    catch (error) {
-        release();
-        throw error;
-    }
-}
 /**
  * Run the per-file config pipeline every raw config object goes through
  * before it is either validated (the local/top-level file) or merged in as
- * an `extends` base: JSONC parse already done by the caller, then version
- * shim, then legacy `stashDir`/`sources[]`/`installed[]` shim, then the
- * legacy `extraParams` lift (#852). Shared by {@link parseAndValidateConfigText}
- * (the local file) and {@link resolveExtendsChain} (each base in the chain) so
- * a fleet-shared base config can carry its own old `configVersion` / legacy
- * shape independently of the file that extends it.
+ * an `extends` base: JSONC parse already done by the caller, then the
+ * `configVersion` read ({@link readConfigVersion}), then the legacy
+ * `stashDir`/`sources[]`/`installed[]` shim, then the legacy `extraParams`
+ * lift (#852). Unknown keys are not an error: the schema drops them in
+ * memory. Shared by {@link parseAndValidateConfigText} (the local file) and
+ * {@link resolveExtendsChain} (each base in the chain) so a fleet-shared base
+ * config can carry its own `configVersion` / legacy shape independently of
+ * the file that extends it.
  */
 function runConfigFilePipeline(text, sourcePath) {
-    const versioned = upgradeConfigVersion(parseConfigText(text, sourcePath), sourcePath);
+    const versioned = readConfigVersion(parseConfigText(text, sourcePath), sourcePath);
     const parsedRaw = migrateLegacySourceShape(versioned, sourcePath);
     return liftExtraParamsOrThrow(parsedRaw, sourcePath);
 }
+/**
+ * `configVersion` is read, never gated on. `"0.9.0"` is the only value akm
+ * has ever shipped, and a document without the field is that same document.
+ * Any other value is named once and the file is read as the current shape
+ * anyway; every ordinary config write and `akm migrate apply`'s `configFile`
+ * step then persist `"0.9.0"`.
+ */
+function readConfigVersion(raw, sourcePath) {
+    const version = raw.configVersion;
+    if (version === CURRENT_CONFIG_VERSION)
+        return raw;
+    if (version !== undefined) {
+        warnOnce(`config:config-version${sourcePath ? `:${sourcePath}` : ""}`, `${sourcePath ?? "config.json"} declares configVersion ${JSON.stringify(version)}; this release reads it as ${CURRENT_CONFIG_VERSION}.`);
+    }
+    return { ...raw, configVersion: CURRENT_CONFIG_VERSION };
+}
 /**
  * #852 (following #815): a config still using legacy `extraParams` keys —
  * e.g. `reasoning_effort`, a documented 0.9.1 workaround — needs to be
@@ -192,49 +163,74 @@ function liftExtraParamsOrThrow(parsedRaw, sourcePath) {
  * keeps around, instead of only getting the final merged `AkmConfig` back.
  */
 function buildEffectiveConfig(liftedLocalRaw, sourcePath) {
-    warnUnknownTopLevelConfigKeys(liftedLocalRaw, sourcePath);
     const withExtends = resolveExtendsChain(liftedLocalRaw, sourcePath);
     const where = sourcePath ? ` at ${sourcePath}` : "";
+    warnUnknownConfigKeys(liftedLocalRaw, sourcePath);
     const parsed = AkmConfigSchema.safeParse(withExtends);
     if (!parsed.success) {
         const lines = parsed.error.issues.map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
-        const needsSchedulerMigration = parsed.error.issues.some((issue) => issue.path[0] === "scheduler" && issue.path.at(-1) === "sourceId");
-        throw new ConfigError(`Invalid config${where}:\n${lines}`, "INVALID_CONFIG_FILE", needsSchedulerMigration
-            ? "Run `akm migrate apply` to bind existing scheduler grants to their source."
-            : undefined);
+        throw new ConfigError(`Invalid config${where}:\n${lines}`, "INVALID_CONFIG_FILE");
     }
     const merged = deepMergeConfig(DEFAULT_CONFIG, parsed.data);
     const finalResult = AkmConfigSchema.safeParse(merged);
     if (!finalResult.success) {
         const lines = finalResult.error.issues.map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
-        const needsSchedulerMigration = finalResult.error.issues.some((issue) => issue.path[0] === "scheduler" && issue.path.at(-1) === "sourceId");
-        throw new ConfigError(`Invalid merged config${sourcePath ? ` at ${sourcePath}` : ""}:\n${lines}`, "INVALID_CONFIG_FILE", needsSchedulerMigration
-            ? "Run `akm migrate apply` to bind existing scheduler grants to their source."
-            : undefined);
+        throw new ConfigError(`Invalid merged config${sourcePath ? ` at ${sourcePath}` : ""}:\n${lines}`, "INVALID_CONFIG_FILE");
     }
     assertUniquePhysicalBundleRoots(finalResult.data, sourcePath);
     return finalResult.data;
 }
-const RETIRED_TOP_LEVEL_CONFIG_KEYS = new Set([
-    "agent",
-    "bindings",
-    "features",
-    "installed",
-    "llm",
-    "modelAliases",
-    "profiles",
-    "sources",
-    "stashDir",
-    "stashes",
-    "writable",
-]);
-function warnUnknownTopLevelConfigKeys(raw, sourcePath) {
-    const known = new Set(listTopLevelConfigKeys());
-    for (const key of Object.keys(raw).sort()) {
-        if (known.has(key) || RETIRED_TOP_LEVEL_CONFIG_KEYS.has(key))
+/**
+ * Retired `index.<passName>` keys that still validate against the generic
+ * per-pass catchall schema (`IndexPassConfigSchema`), so `resolveSchemaAt`
+ * below never returns `undefined` for them and the walk would otherwise
+ * treat them as a live, ordinary pass. Named here so the same three
+ * guarantees apply as any other retired config key (AGENTS.md "Reading
+ * persisted data"): a config setting one keeps loading, is named once by
+ * the unknown-key warning, and is dropped only by `akm migrate apply`.
+ * Both were retired in 0.9.17-alpha.9: `index.graph` (the LLM entity-graph
+ * extraction pass) and `index.metadataEnhance` (LLM metadata enrichment).
+ */
+const RETIRED_CATCHALL_KEY_PATHS = new Set(["index.graph", "index.metadataEnhance"]);
+/**
+ * Every dotted key in `raw` the schema does not know, at any depth (arrays
+ * are not descended). Unknown keys are never an error: they are a typo, or a
+ * key another release used. Reads keep them (they round-trip through
+ * ordinary writes, so a newer release's settings survive a downgrade);
+ * `akm migrate apply` drops them.
+ */
+export function unknownConfigKeyPaths(root, node = root, prefix = []) {
+    const found = [];
+    for (const key of Object.keys(node).sort()) {
+        const keyPath = [...prefix, key];
+        if (RETIRED_CATCHALL_KEY_PATHS.has(keyPath.join(".")) || resolveSchemaAt(keyPath, root) === undefined) {
+            found.push(keyPath);
             continue;
-        warnOnce(`config:unknown-key:${sourcePath ?? "inline"}:${key}`, `Unknown config key ${JSON.stringify(key)}${sourcePath ? ` at ${sourcePath}` : ""} has no defined akm behavior. Check the spelling or remove it.`);
+        }
+        const value = node[key];
+        if (isPlainConfigObject(value))
+            found.push(...unknownConfigKeyPaths(root, value, keyPath));
+    }
+    return found;
+}
+function warnUnknownConfigKeys(raw, sourcePath) {
+    for (const keyPath of unknownConfigKeyPaths(raw)) {
+        const dotted = keyPath.join(".");
+        warnOnce(`config:unknown-key:${sourcePath ?? "inline"}:${dotted}`, `Unknown config key ${JSON.stringify(dotted)}${sourcePath ? ` at ${sourcePath}` : ""} has no defined akm behavior and is ignored. Check the spelling; a key retired by this release or added by a newer one is dropped by \`akm migrate apply\`.`);
+    }
+}
+function deleteConfigPath(node, keyPath) {
+    let cursor = node;
+    for (const segment of keyPath.slice(0, -1)) {
+        if (!isPlainConfigObject(cursor))
+            return;
+        cursor = cursor[segment];
     }
+    if (isPlainConfigObject(cursor))
+        delete cursor[keyPath[keyPath.length - 1]];
+}
+function isPlainConfigObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function assertUniquePhysicalBundleRoots(config, sourcePath) {
     const owners = new Map();
@@ -250,11 +246,10 @@ function assertUniquePhysicalBundleRoots(config, sourcePath) {
  * Parse raw config text and validate via Zod.
  * ({@link AkmConfigSchema}). Returns the merged-with-defaults AkmConfig.
  *
- * The schema accepts only the current config version. A known older version
- * is auto-upgraded in memory first (see `./config-version-shim`); anything
- * else — including anything newer — is rejected before the canonical shape
- * is validated. When the config sets `extends` (#945), its resolved chain is
- * deep-merged underneath before validation — see {@link resolveExtendsChain}.
+ * `configVersion` is read as the current version whatever it says (see
+ * {@link readConfigVersion}). When the config sets `extends` (#945), its
+ * resolved chain is deep-merged underneath before validation — see
+ * {@link resolveExtendsChain}.
  */
 export function parseAndValidateConfigText(text, sourcePath) {
     const liftedConfig = runConfigFilePipeline(text, sourcePath);
@@ -287,7 +282,7 @@ function collectExtendsLayers(localRaw, configPath) {
         }
         visited.add(resolvedPath);
         const baseRaw = runConfigFilePipeline(text, resolvedPath);
-        warnUnknownTopLevelConfigKeys(baseRaw, resolvedPath);
+        warnUnknownConfigKeys(baseRaw, resolvedPath);
         layers.push({ ref, raw: baseRaw });
         current = baseRaw;
         currentPath = resolvedPath;
@@ -663,6 +658,46 @@ function configWriteBody(localRaw, current, next, persistTopLevelKeys = []) {
     }
     return ordered;
 }
+/**
+ * The migrator's one config step. The reader already tolerates every shape
+ * akm has written (`configVersion` read as current, legacy source layout,
+ * `extraParams` lift, unknown keys dropped); this writes that current shape back to
+ * `config.json` — the same body `mutateConfig` writes — so the tolerance
+ * becomes durable. Reports without writing unless `apply` is set.
+ */
+export function normalizeConfigFile(configPath, options) {
+    return withConfigLock(() => {
+        const text = readConfigText(configPath);
+        if (text === undefined)
+            return { keys: [], changed: false, applied: false };
+        const raw = parseConfigText(text, configPath);
+        const localRaw = runConfigFilePipeline(text, configPath);
+        const current = buildEffectiveConfig(localRaw, configPath);
+        const next = validateCompleteConfig({ ...current, configVersion: CURRENT_CONFIG_VERSION });
+        const body = withSchedulerOnDisk(configWriteBody(localRaw, current, next), next);
+        for (const keyPath of unknownConfigKeyPaths(body))
+            deleteConfigPath(body, keyPath);
+        // `improve.strategies["graph-refresh"]` is schema-valid (any name is a
+        // legal custom-strategy key), so it never reaches the unknown-key sweep
+        // above. It can only be a leftover override of the deleted graph-refresh
+        // built-in (0.9.17-alpha.9) — resolveImproveStrategy now refuses that
+        // name unconditionally, so the override can never apply again. Drop it
+        // the same way any other retired key is dropped: only by `akm migrate
+        // apply`, never by an ordinary write.
+        const strategies = body.improve?.strategies;
+        if (strategies && Object.hasOwn(strategies, "graph-refresh"))
+            delete strategies["graph-refresh"];
+        const keys = [...new Set([...Object.keys(raw), ...Object.keys(body)])]
+            .filter((key) => JSON.stringify(raw[key]) !== JSON.stringify(body[key]))
+            .sort();
+        if (keys.length === 0 || !options.apply)
+            return { keys, changed: keys.length > 0, applied: false };
+        const backup = backupExistingConfig(configPath);
+        writeConfigAtomic(configPath, body);
+        cachedConfig = undefined;
+        return { keys, changed: true, applied: true, ...(backup ? { backupPath: backup.timestamped } : {}) };
+    });
+}
 /**
  * Mutate config under one fail-closed lock spanning read, merge, validation,
  * ordinary backup, and atomic write.
@@ -716,6 +751,61 @@ export async function mutateConfigWithPrecommit(mutate, precommit, options) {
         release();
     }
 }
+const UNBOUND_SCHEDULER_SOURCE_ID = `sha256:${"0".repeat(64)}`;
+/**
+ * The source identity 0.9.16 bound a scheduler grant to: the configured
+ * bundle's source id, or the implicit `AKM_BUNDLE_DIR` stash's. `undefined`
+ * when the bundle is not active on this host.
+ */
+export function schedulerSourceIdFor(config, bundleId) {
+    if (isBundleEnabled(config, bundleId))
+        return bundleSourceId(config, bundleId);
+    if (config.bundles?.[bundleId] !== undefined || !process.env.AKM_BUNDLE_DIR?.trim())
+        return undefined;
+    try {
+        const root = resolveStashDir();
+        const implicitId = deriveBundleId(undefined, root, new Set(Object.keys(config.bundles ?? {})));
+        return implicitId === bundleId ? filesystemBundleSourceId(root) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * `scheduler.enabled` is a list of refs in memory but is written in the
+ * `{kind, ref, sourceId}` shape 0.9.16 reads, so that release still runs
+ * against a config this one wrote (the upgrade rehearsal's read-back). This
+ * release reads either shape; the object form can go once no supported
+ * release is strict about it.
+ */
+function schedulerEnabledOnDisk(config) {
+    const enabled = config.scheduler?.enabled;
+    if (enabled === undefined)
+        return undefined;
+    return enabled.map((ref) => {
+        let bundle;
+        let conceptId = "";
+        try {
+            const parsed = parseBundleRef(ref);
+            bundle = parsed.bundle;
+            conceptId = parsed.conceptId;
+        }
+        catch {
+            return ref;
+        }
+        return {
+            kind: conceptId.startsWith("workflows/") ? "workflow" : "task",
+            ref,
+            sourceId: (bundle !== undefined ? schedulerSourceIdFor(config, bundle) : undefined) ?? UNBOUND_SCHEDULER_SOURCE_ID,
+        };
+    });
+}
+function withSchedulerOnDisk(body, config) {
+    const onDisk = schedulerEnabledOnDisk(config);
+    if (onDisk === undefined || !isPlainConfigObject(body.scheduler))
+        return body;
+    return { ...body, scheduler: { ...body.scheduler, enabled: onDisk } };
+}
 /**
  * Strip literal apiKey fields before writing config to disk.
  * API keys are expected to come from environment variables
@@ -780,7 +870,7 @@ export function sanitizeConfigForWrite(config) {
             warn(`Config sanitizer dropped registry entr${droppedRegistries.length === 1 ? "y" : "ies"} with URL credentials before writing to disk:\n  - ${droppedRegistries.join("\n  - ")}\n\nRegistry URLs must be credential-free; configure a credential-free HTTPS endpoint.`);
         }
     }
-    return sanitized;
+    return withSchedulerOnDisk(sanitized, config);
 }
 export function updateConfig(partial) {
     return mutateConfig((current) => deepMergeConfig(current, partial)).config;
@@ -830,23 +920,6 @@ export function resolveSecret(value, resolveFromStore) {
         return resolved ?? "";
     });
 }
-/**
- * Read a per-pass {@link IndexPassConfig} entry from {@link IndexConfig},
- * filtering out the reserved feature-section keys so callers don't mistake
- * `metadataEnhance` for a pass.
- */
-/** Reserved well-known keys on IndexConfig that are NOT per-pass entries. */
-const INDEX_RESERVED_KEYS = new Set(["metadataEnhance"]);
-export function getIndexPassConfig(config, passName) {
-    if (!config)
-        return undefined;
-    if (INDEX_RESERVED_KEYS.has(passName))
-        return undefined;
-    const entry = config[passName];
-    if (!entry || typeof entry !== "object")
-        return undefined;
-    return entry;
-}
 // Re-export source runtime helpers — implementation lives in config-sources.ts.
 export { bundleComponentConfig, bundleContentRoot, bundleContentRoots, bundleEntryToSourceEntry, bundleKeyForContentRoot, bundlePhysicalContentRoot, bundleSourceId, bundlesToSourceEntries, installedSourceDescriptor, isBundleEnabled, parseSourceSpec, primaryBundlePath, resolveActiveConfiguredSources, resolveConfiguredSources, } from "./config-sources.js";
 /**

package/dist/core/config/engine-semantics.js

@@ -6,7 +6,6 @@ export const BUILTIN_IMPROVE_STRATEGY_NAMES = [
     "default",
     "quick",
     "thorough",
-    "graph-refresh",
     "consolidate",
     "catchup",
     "reflect-distill",
@@ -18,7 +17,6 @@ export const IMPROVE_PROCESS_ENGINE_CAPABILITIES = {
     distill: "llm",
     consolidate: "llm",
     memoryInference: "llm",
-    graphExtraction: "llm",
     extract: "llm",
     validation: "llm",
     triage: "runner",

package/dist/core/config/legacy-source-shape-shim.js

@@ -55,20 +55,29 @@ function filesystemLocator(bundle) {
         return undefined;
     return path.resolve(bundle.path);
 }
-export function migrateLegacySourceShape(raw, sourcePath) {
-    const hasStashDir = typeof raw.stashDir === "string" && raw.stashDir.trim().length > 0;
-    const hasSources = Array.isArray(raw.sources) && raw.sources.length > 0;
+/**
+ * Pure legacy `stashDir`/`sources[]`/`installed` -> `bundles`/`defaultBundle`
+ * conversion. Triggers on key *presence* (not on the value being usable), so
+ * an unusable value — `stashDir: ""`, `sources: []` — is still removed along
+ * with the rest of the legacy shape; only a usable `stashDir` or `sources[]`
+ * entry is actually folded into `bundles`. Never warns — see
+ * {@link migrateLegacySourceShape} for the warn-once wrapper callers use.
+ */
+export function convertLegacySourceShape(raw) {
+    const hasStashDir = "stashDir" in raw;
+    const hasSources = "sources" in raw;
     const hasInstalled = "installed" in raw && raw.installed !== undefined;
     if (!hasStashDir && !hasSources && !hasInstalled)
-        return raw;
+        return { config: raw, converted: [] };
     const { stashDir: _stashDir, sources: _sources, installed: _installed, ...rest } = raw;
     const bundles = isPlainRecord(rest.bundles) ? { ...rest.bundles } : {};
     let defaultBundle = typeof rest.defaultBundle === "string" ? rest.defaultBundle : undefined;
-    if (hasStashDir) {
+    const usableStashDir = typeof raw.stashDir === "string" && raw.stashDir.trim().length > 0;
+    if (usableStashDir) {
         bundles.stash = { path: raw.stashDir, writable: true };
         defaultBundle ??= "stash";
     }
-    if (hasSources) {
+    if (Array.isArray(raw.sources)) {
         raw.sources.forEach((entry, index) => {
             const converted = bundleFromLegacySource(entry, index);
             if (!converted)
@@ -81,8 +90,28 @@ export function migrateLegacySourceShape(raw, sourcePath) {
             defaultBundle ??= key;
         });
     }
-    const droppedKeys = [hasStashDir && "stashDir", hasSources && "sources", hasInstalled && "installed"].filter(Boolean);
+    const converted = [hasStashDir && "stashDir", hasSources && "sources", hasInstalled && "installed"].filter((key) => typeof key === "string");
+    // Only add a `bundles` key when there is something to say: either a
+    // legacy entry actually converted into one, or the config already had a
+    // `bundles` map (preserved as-is). An unusable `stashDir: ""` / `sources: []`
+    // with no pre-existing `bundles` should just disappear, not leave behind
+    // an empty `bundles: {}`.
+    const hasBundles = Object.keys(bundles).length > 0 || isPlainRecord(rest.bundles);
+    return {
+        config: { ...rest, ...(hasBundles ? { bundles } : {}), ...(defaultBundle !== undefined ? { defaultBundle } : {}) },
+        converted,
+    };
+}
+/**
+ * Warn-once wrapper around {@link convertLegacySourceShape} for the
+ * in-memory read path: converts the legacy shape and, when it removed
+ * anything, warns once that `akm migrate apply` will persist the rewrite.
+ */
+export function migrateLegacySourceShape(raw, sourcePath) {
+    const { config, converted } = convertLegacySourceShape(raw);
+    if (converted.length === 0)
+        return config;
     const where = sourcePath ? ` at ${sourcePath}` : "";
-    warnOnce(`legacy-source-shape${sourcePath ? `:${sourcePath}` : ""}`, `Config${where} uses the retired ${droppedKeys.join("/")} shape — auto-migrated in memory to \`bundles\`/\`defaultBundle\`. Run \`akm migrate apply\` to rewrite the config file and silence this warning.`);
-    return { ...rest, bundles, ...(defaultBundle !== undefined ? { defaultBundle } : {}) };
+    warnOnce(`legacy-source-shape${sourcePath ? `:${sourcePath}` : ""}`, `Config${where} uses the retired ${converted.join("/")} shape — auto-migrated in memory to \`bundles\`/\`defaultBundle\`. Run \`akm migrate apply\` to rewrite the config file and silence this warning.`);
+    return config;
 }

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

@@ -27,11 +27,7 @@ export const EmbeddingConnectionConfigSchema = z
     endpoint: z.string().optional(),
     model: z.string().optional(),
     apiKey: symbolicOrWarnApiKey("embedding.apiKey").optional(),
-    // Bounded to the index schema's own vec-table guard (1–4096,
-    // storage/repositories/index-schema.ts) so an out-of-range dimension
-    // fails at config validation with a clear message instead of crashing
-    // `akm index` when ensureSchema rejects it (§24.2 "Semantic" gate).
-    dimension: positiveInt.max(4096).optional(),
+    dimension: positiveInt.optional(),
     localModel: z.string().min(1).optional(),
     /**
      * Per-document token cap applied BEFORE batching (default 512,
@@ -68,6 +64,25 @@ export const EmbeddingConnectionConfigSchema = z
      * no retry — every batch that hit it was silently dropped (#954).
      */
     timeoutMs: positiveInt.optional(),
+    /**
+     * How long search waits for the query embedding (default 3000,
+     * `DEFAULT_QUERY_EMBED_TIMEOUT_MS` in `src/indexer/search/db-search.ts`).
+     * On expiry the search is served by keyword ranking alone, with a warning.
+     */
+    queryTimeoutMs: positiveInt.optional(),
+    /**
+     * Text sent to the model around a search query, `{text}` marking the
+     * query (a template without it is a prefix). Overrides the preset matched
+     * on the model name (`src/llm/embedders/profile.ts`); `""` sends the query
+     * as is.
+     */
+    queryTemplate: z.string().optional(),
+    /**
+     * Text sent to the model around each document at index time, as
+     * `queryTemplate`. Part of the embedding fingerprint: changing it
+     * re-embeds the index.
+     */
+    documentTemplate: z.string().optional(),
     /**
      * Overrides the fixed in-flight request window (#954, added after field
      * evidence from multi-slot local servers). Bounded 1-16. Unset keeps

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

@@ -77,6 +77,11 @@ const LlmEngineSchema = z
     maxTokens: positiveInt.optional(),
     timeoutMs: timeoutMsField,
     concurrency: positiveInt.optional(),
+    // Same user-settable override LlmConnectionConfigSchema declares above; a
+    // named `kind: "llm"` engine is validated by THIS object, so without the
+    // field here the unknown-key walk reported a live setting as unknown and
+    // `akm migrate apply` dropped it from config.json.
+    supportsJsonSchema: z.boolean().optional(),
     extraParams: ExtraParamsSchema.optional(),
     contextLength: positiveInt.optional(),
     enableThinking: z.boolean().optional(),

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

@@ -20,4 +20,4 @@ export const ExecutionPolicyConfigSchema = z
         }
     }),
 })
-    .strict();
+    .passthrough();

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

@@ -27,4 +27,4 @@ export const ExperimentalConfigSchema = z
      */
     improveAutonomy: z.boolean().optional(),
 })
-    .strict();
+    .passthrough();