akm-cli 0.9.1 → 0.9.2-alpha.2

package/dist/commands/sources/schema-repair.js

@@ -9,8 +9,7 @@
  * call per asset. Results are recorded as `schema_repair_invoked` events.
  *
  * This module is extracted from `improve.ts` to make the repair logic
- * independently testable and to use the `tryLlmFeature` seam rather than raw
- * `chatCompletion`.
+ * independently testable and to use the shared structured execution seam.
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -18,12 +17,14 @@ import { assembleAsset } from "../../core/asset/asset-serialize.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { parseRefInput } from "../../core/asset/resolve-ref.js";
 import { authoringRulesForType } from "../../core/authoring-rules.js";
+import { ConfigError } from "../../core/errors.js";
 import { appendEvent, readEvents } from "../../core/events.js";
 import { parseEmbeddedJsonResponse } from "../../core/parse.js";
 import { resolveStandardsContext } from "../../core/standards/resolve-standards-context.js";
 import { info } from "../../core/warn.js";
 import { resolveAssetPath } from "../../indexer/walk/path-resolver.js";
-import { chatCompletion } from "../../llm/client.js";
+import { disposeLoweredExecutionDispatchLease } from "../../integrations/agent/execution-lowering.js";
+import { callStructured, preflightStructuredLlmRunner } from "../../llm/structured-call.js";
 import { createProposal, isProposalSkipped } from "../proposal/repository.js";
 // ── Constants ────────────────────────────────────────────────────────────────
 /** Minimum gap between schema-repair attempts on the same asset. */
@@ -37,36 +38,23 @@ const SCHEMA_REPAIR_COOLDOWN_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
  */
 const SCHEMA_REPAIR_MAX_ATTEMPTS = 3;
 const SCHEMA_REPAIR_WINDOW_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
-// ── Main ─────────────────────────────────────────────────────────────────────
-/**
- * Run the schema-repair loop for a batch of validation failures.
- * Returns a list of per-asset outcome records and the set of refs whose live
- * files were repaired. Queued proposals never count as live repairs.
- */
-export async function runSchemaRepairPass(failures, options) {
-    const repairs = [];
-    const repairedRefs = new Set();
-    const { startMs, budgetMs, llmConfig, stashDir, findFilePath = defaultFindFilePath, isLessonCandidateFn = defaultIsLessonCandidate, chatFn = chatCompletion, } = options;
-    if (!stashDir) {
-        throw new Error("runSchemaRepairPass requires stashDir so repairs route through the proposal queue");
-    }
+async function classifySchemaRepairs(args) {
+    const { failures, startMs, budgetMs, stashDir, findFilePath, isLessonCandidateFn, repairs } = args;
+    const eligibleRepairs = [];
+    const pendingErrors = [];
     for (const failure of failures) {
         if (Date.now() - startMs >= budgetMs)
             break;
-        // Cooldown: skip repair if we ran it successfully recently.
         const recentRepairs = readEvents({ type: "schema_repair_invoked", ref: failure.ref });
         const lastRepair = recentRepairs.events
-            .filter((e) => e.metadata?.outcome === "queued")
+            .filter((event) => event.metadata?.outcome === "queued")
             .sort((a, b) => new Date(b.ts ?? 0).getTime() - new Date(a.ts ?? 0).getTime())[0];
         if (lastRepair?.ts && Date.now() - new Date(lastRepair.ts).getTime() < SCHEMA_REPAIR_COOLDOWN_MS) {
             repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "skipped" });
             continue;
         }
-        // O-6 / #379: Cap total attempts at SCHEMA_REPAIR_MAX_ATTEMPTS per SCHEMA_REPAIR_WINDOW_MS.
-        // Prevents indefinite nightly re-repair of assets whose source is genuinely ambiguous.
-        // After the cap is reached, the asset is skipped until the window rolls over.
         const windowStart = Date.now() - SCHEMA_REPAIR_WINDOW_MS;
-        const attemptsInWindow = recentRepairs.events.filter((e) => e.ts !== undefined && new Date(e.ts).getTime() >= windowStart).length;
+        const attemptsInWindow = recentRepairs.events.filter((event) => event.ts !== undefined && new Date(event.ts).getTime() >= windowStart).length;
         if (attemptsInWindow >= SCHEMA_REPAIR_MAX_ATTEMPTS) {
             repairs.push({
                 ref: failure.ref,
@@ -77,32 +65,23 @@ export async function runSchemaRepairPass(failures, options) {
             continue;
         }
         const filePath = await findFilePath(failure.ref, stashDir);
-        if (!filePath) {
-            repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "skipped" });
-            continue;
-        }
-        if (path.extname(filePath).toLowerCase() !== ".md") {
+        if (!filePath || path.extname(filePath).toLowerCase() !== ".md") {
             repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "skipped" });
             continue;
         }
         try {
             const raw = fs.readFileSync(filePath, "utf8");
-            const fm = parseFrontmatter(raw);
+            const frontmatter = parseFrontmatter(raw);
             const missingFields = [];
-            if (!fm.data.description)
+            if (!frontmatter.data.description)
                 missingFields.push("description");
-            if (isLessonCandidateFn(failure.ref) && !fm.data.when_to_use)
+            if (isLessonCandidateFn(failure.ref) && !frontmatter.data.when_to_use)
                 missingFields.push("when_to_use");
             if (missingFields.length === 0) {
                 repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "skipped" });
                 continue;
             }
             const fieldList = missingFields.join(" and ");
-            info(`[improve] schema-repair ${failure.ref} (${fieldList})`);
-            const bodyPreview = (fm.content ?? raw).slice(0, 2000);
-            // Standards "rulebook" for this target — wiki schema (wiki page) or stash
-            // convention/meta facts (non-wiki asset). `resolveStandardsContext`
-            // dispatches on the ref.
             const standardsContext = resolveStandardsContext(failure.ref, stashDir);
             const standardsSection = standardsContext.trim()
                 ? `\n\nStandards to follow (the rulebook for this target):\n${standardsContext.trim()}`
@@ -110,75 +89,175 @@ export async function runSchemaRepairPass(failures, options) {
             const assetType = parseRefInput(failure.ref).type;
             const authoringRules = authoringRulesForType(assetType);
             const authoringRulesSection = authoringRules ? `\n\n${authoringRules}` : "";
-            const llmResponse = await chatFn(llmConfig, [
-                {
-                    role: "system",
-                    content: `You generate concise asset frontmatter fields. Respond with a JSON object containing only the missing fields. No prose, no markdown fences.`,
-                },
-                {
-                    role: "user",
-                    content: `Generate the missing frontmatter fields (${fieldList}) for this ${assetType} asset. Return ONLY valid JSON like {"description": "...", "when_to_use": "..."}${standardsSection}${authoringRulesSection}\n\n${bodyPreview}`,
-                },
-            ]);
-            const parsed = parseEmbeddedJsonResponse(llmResponse.trim());
-            if (!parsed) {
-                repairs.push({
-                    ref: failure.ref,
-                    reason: failure.reason,
-                    outcome: "error",
-                    error: "LLM returned unparseable JSON for schema repair",
-                });
-                continue;
-            }
-            const newFm = { ...fm.data };
-            if (parsed.description)
-                newFm.description = parsed.description;
-            if (parsed.when_to_use)
-                newFm.when_to_use = parsed.when_to_use;
-            const newContent = assembleAsset(newFm, fm.content);
-            // M-3 / #387: Route through proposal queue instead of writing directly to
-            // disk. This restores akm's safety invariant — the proposal queue is the
-            // only path to a committed asset write. LLM-generated `description` /
-            // `when_to_use` fields can be incorrect; routing through the queue makes
-            // them human-reviewable before they affect search ranking and curate hints.
-            // mem0 open gaps (arXiv:2504.19413) — any LLM write to a memory field
-            // should be human-reviewable.
-            const proposalResult = createProposal(stashDir, {
-                ref: failure.ref,
-                source: "schema-repair",
-                // §23.6 fingerprint model-id term (WI-6.4).
-                modelId: llmConfig.model,
-                payload: {
-                    content: newContent,
-                    ...(Object.keys(newFm).length > 0 ? { frontmatter: newFm } : {}),
-                },
+            eligibleRepairs.push({
+                failure,
+                frontmatter,
+                fieldList,
+                messages: [
+                    {
+                        role: "system",
+                        content: "You generate concise asset frontmatter fields. Respond with a JSON object containing only the missing fields. No prose, no markdown fences.",
+                    },
+                    {
+                        role: "user",
+                        content: `Generate the missing frontmatter fields (${fieldList}) for this ${assetType} asset. Return ONLY valid JSON like {"description": "...", "when_to_use": "..."}${standardsSection}${authoringRulesSection}\n\n${(frontmatter.content ?? raw).slice(0, 2000)}`,
+                    },
+                ],
             });
-            if (isProposalSkipped(proposalResult)) {
-                info(`[improve] schema-repair proposal skipped for ${failure.ref}: ${proposalResult.message}`);
-                repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "skipped" });
-                continue;
-            }
-            info(`[improve] schema-repair queued: ${failure.ref} (proposal id: ${proposalResult.id})`);
+        }
+        catch (error) {
+            pendingErrors.push({ ref: failure.ref, reason: failure.reason, outcome: "error", error: String(error) });
+        }
+    }
+    return { eligibleRepairs, pendingErrors };
+}
+// ── Main ─────────────────────────────────────────────────────────────────────
+/**
+ * Run the schema-repair loop for a batch of validation failures.
+ * Returns a list of per-asset outcome records and the set of refs whose live
+ * files were repaired. Queued proposals never count as live repairs. Invalid
+ * symbolic credentials reject with {@link ConfigError} before any repair
+ * proposal or per-ref event is written.
+ */
+export async function runSchemaRepairPass(failures, options) {
+    const repairs = [];
+    const repairedRefs = new Set();
+    const { startMs, budgetMs, stashDir, findFilePath = defaultFindFilePath, isLessonCandidateFn = defaultIsLessonCandidate, chatFn, } = options;
+    const llmRunner = options.llmRunner ?? null;
+    if (!llmRunner)
+        throw new Error("runSchemaRepairPass requires a resolved LLM runner");
+    if (!stashDir) {
+        throw new Error("runSchemaRepairPass requires stashDir so repairs route through the proposal queue");
+    }
+    // Classify the entire batch using read-only work before credential lookup or
+    // proposal/event persistence. A missing required credential therefore aborts
+    // the eligible batch atomically instead of leaving an earlier proposal behind.
+    const { eligibleRepairs, pendingErrors } = await classifySchemaRepairs({
+        failures,
+        startMs,
+        budgetMs,
+        stashDir,
+        findFilePath,
+        isLessonCandidateFn,
+        repairs,
+    });
+    if (eligibleRepairs.length === 0) {
+        for (const repair of pendingErrors) {
             appendEvent({
                 eventType: "schema_repair_invoked",
-                ref: failure.ref,
-                metadata: { outcome: "queued", reason: failure.reason, proposalId: proposalResult.id },
-            });
-            repairs.push({
-                ref: failure.ref,
-                reason: failure.reason,
-                outcome: "queued",
-                proposalId: proposalResult.id,
+                ref: repair.ref,
+                metadata: { outcome: "error", reason: repair.reason, error: repair.error },
             });
+            repairs.push(repair);
         }
-        catch (e) {
+        return { repairs, repairedRefs };
+    }
+    const dispatchLease = await preflightStructuredLlmRunner(llmRunner);
+    try {
+        for (const repair of pendingErrors) {
             appendEvent({
                 eventType: "schema_repair_invoked",
-                ref: failure.ref,
-                metadata: { outcome: "error", reason: failure.reason, error: String(e) },
+                ref: repair.ref,
+                metadata: { outcome: "error", reason: repair.reason, error: repair.error },
             });
-            repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "error", error: String(e) });
+            repairs.push(repair);
         }
+        for (const { failure, frontmatter: fm, fieldList, messages } of eligibleRepairs) {
+            let loweringNotices = [];
+            const noticeFields = () => loweringNotices.length > 0 ? { notices: loweringNotices } : {};
+            try {
+                info(`[improve] schema-repair ${failure.ref} (${fieldList})`);
+                const llmResponse = await callStructured({
+                    feature: "schema_repair",
+                    runner: llmRunner,
+                    lease: dispatchLease,
+                    messages,
+                    ...(chatFn ? { request: { chat: chatFn } } : {}),
+                    onNotices: (value) => {
+                        loweringNotices = value;
+                    },
+                    parse: (rawResponse) => rawResponse ?? "",
+                    onError: () => "",
+                    fallback: "",
+                });
+                const parsed = parseEmbeddedJsonResponse(llmResponse.trim());
+                if (!parsed) {
+                    repairs.push({
+                        ref: failure.ref,
+                        reason: failure.reason,
+                        outcome: "error",
+                        error: "LLM returned unparseable JSON for schema repair",
+                        ...noticeFields(),
+                    });
+                    continue;
+                }
+                const newFm = { ...fm.data };
+                if (parsed.description)
+                    newFm.description = parsed.description;
+                if (parsed.when_to_use)
+                    newFm.when_to_use = parsed.when_to_use;
+                const newContent = assembleAsset(newFm, fm.content);
+                // M-3 / #387: Route through proposal queue instead of writing directly to
+                // disk. This restores akm's safety invariant — the proposal queue is the
+                // only path to a committed asset write. LLM-generated `description` /
+                // `when_to_use` fields can be incorrect; routing through the queue makes
+                // them human-reviewable before they affect search ranking and curate hints.
+                // mem0 open gaps (arXiv:2504.19413) — any LLM write to a memory field
+                // should be human-reviewable.
+                const proposalResult = createProposal(stashDir, {
+                    ref: failure.ref,
+                    source: "schema-repair",
+                    // §23.6 fingerprint model-id term (WI-6.4).
+                    modelId: llmRunner.connection.model,
+                    payload: {
+                        content: newContent,
+                        ...(Object.keys(newFm).length > 0 ? { frontmatter: newFm } : {}),
+                    },
+                });
+                if (isProposalSkipped(proposalResult)) {
+                    info(`[improve] schema-repair proposal skipped for ${failure.ref}: ${proposalResult.message}`);
+                    repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "skipped", ...noticeFields() });
+                    continue;
+                }
+                info(`[improve] schema-repair queued: ${failure.ref} (proposal id: ${proposalResult.id})`);
+                appendEvent({
+                    eventType: "schema_repair_invoked",
+                    ref: failure.ref,
+                    metadata: {
+                        outcome: "queued",
+                        reason: failure.reason,
+                        proposalId: proposalResult.id,
+                        ...noticeFields(),
+                    },
+                });
+                repairs.push({
+                    ref: failure.ref,
+                    reason: failure.reason,
+                    outcome: "queued",
+                    proposalId: proposalResult.id,
+                    ...noticeFields(),
+                });
+            }
+            catch (e) {
+                if (e instanceof ConfigError)
+                    throw e;
+                appendEvent({
+                    eventType: "schema_repair_invoked",
+                    ref: failure.ref,
+                    metadata: { outcome: "error", reason: failure.reason, error: String(e), ...noticeFields() },
+                });
+                repairs.push({
+                    ref: failure.ref,
+                    reason: failure.reason,
+                    outcome: "error",
+                    error: String(e),
+                    ...noticeFields(),
+                });
+            }
+        }
+    }
+    finally {
+        disposeLoweredExecutionDispatchLease(dispatchLease);
     }
     return { repairs, repairedRefs };
 }

package/dist/commands/sources/self-update.js

@@ -7,29 +7,17 @@ import fs from "node:fs";
 import path from "node:path";
 import { fetchWithRetry, IS_WINDOWS, ResponseTooLargeError, readBodyWithByteCap, readChunkWithDeadline, } from "../../core/common.js";
 import { ConfigError } from "../../core/errors.js";
+import { upgradeHistoricalStateDatabase } from "../../core/state-db.js";
 import { warn } from "../../core/warn.js";
 import { githubHeaders } from "../../integrations/github.js";
 import { getDirname, mainPath, semverOrder } from "../../runtime.js";
-import { resolveAkmInvocation } from "../../tasks/resolve-akm-bin.js";
 const REPO = "itlackey/akm";
 const DEFAULT_PACKAGE_NAME = "akm-cli";
 const NODE_MODULES_SEGMENT = "/node_modules/";
 const BUN_GLOBAL_INSTALL_PATTERN = /(^|\/)\.bun\/(?:[^/]+\/)+node_modules\//;
 const PNPM_GLOBAL_INSTALL_PATTERN = /(^|\/)(?:pnpm\/global|\.pnpm-global)(?:\/\d+)?\/node_modules\//;
-const MIGRATION_CONTRACT_VERSION = "0.9.0-rc.0";
-const MIGRATION_CONTRACT_BLOCKED_MESSAGE = "AKM 0.8 does not implement the migrate command or the --migration-config upgrade contract, so self-update cannot safely cross into 0.9. " +
-    "Prepare the 0.9 config and an independent backup, install or stage the 0.9 binary manually, then use the new binary to run: " +
-    "akm migrate apply --config <prepared-0.9.json>. See docs/migration/v0.8-to-v0.9.md.";
 const MAX_BINARY_DOWNLOAD_BYTES = 256 * 1024 * 1024;
 const MAX_CHECKSUM_METADATA_BYTES = 1024 * 1024;
-export function defaultMigrationCommand(preparedConfigPath) {
-    const configArgs = preparedConfigPath ? ["--config", preparedConfigPath] : [];
-    return {
-        preflight: (akmBin) => runRequiredCommand(akmBin, ["migrate", "status"], "Migration preflight"),
-        stagedPreflight: (akmBin) => runRequiredCommand(akmBin, ["migrate", "status", ...configArgs], "Staged migration preflight"),
-        apply: (akmBin) => runRequiredCommand(akmBin, ["migrate", "apply", ...configArgs], "Migration apply"),
-    };
-}
 /**
  * Bounds on the binary body read. `fetchWithTimeout`'s timer only covers
  * time-to-HEADERS — it is cleared the moment `fetch` resolves — so without
@@ -184,7 +172,6 @@ export async function performUpgrade(check, opts, dependencies) {
     const { currentVersion, latestVersion, installMethod } = check;
     const force = opts?.force === true;
     const skipPostUpgrade = opts?.skipPostUpgrade === true;
-    const migration = dependencies?.migration ?? defaultMigrationCommand(opts?.migrationConfig);
     // All install methods can short-circuit here unless the user explicitly forces an upgrade.
     if (!check.updateAvailable && !force) {
         return {
@@ -195,11 +182,6 @@ export async function performUpgrade(check, opts, dependencies) {
             message: `akm v${currentVersion} is already the latest version`,
         };
     }
-    if (latestVersion &&
-        semverOrder(currentVersion, MIGRATION_CONTRACT_VERSION) < 0 &&
-        semverOrder(latestVersion, MIGRATION_CONTRACT_VERSION) >= 0) {
-        throw new ConfigError(MIGRATION_CONTRACT_BLOCKED_MESSAGE, "UPGRADE_BLOCKED");
-    }
     const packageManagerCommand = getPackageManagerUpgradeCommand(installMethod);
     if (packageManagerCommand) {
         return runPackageManagerUpgrade({
@@ -207,8 +189,8 @@ export async function performUpgrade(check, opts, dependencies) {
             currentVersion,
             latestVersion,
             installMethod,
-            migration,
             skipPostUpgrade,
+            upgradeState: dependencies?.upgradeHistoricalStateDatabase ?? upgradeHistoricalStateDatabase,
         });
     }
     if (installMethod === "unknown") {
@@ -307,14 +289,6 @@ export async function performUpgrade(check, opts, dependencies) {
                 `Set AKM_UPGRADE_SKIP_CHECKSUM=1 to bypass (not recommended).`);
         }
     }
-    try {
-        migration.preflight(execPath);
-        migration.stagedPreflight(stagedPath);
-    }
-    catch (err) {
-        removeFileBestEffort(stagedPath);
-        throw err;
-    }
     if (fs.existsSync(backupPath)) {
         removeFileBestEffort(stagedPath);
         throw new ConfigError(`Refusing to overwrite retained previous binary at ${backupPath}.`, "UPGRADE_BLOCKED");
@@ -333,14 +307,7 @@ export async function performUpgrade(check, opts, dependencies) {
         }
         throw err;
     }
-    try {
-        migration.apply(execPath);
-    }
-    catch (err) {
-        const detail = err instanceof Error ? err.message : String(err);
-        throw new Error(`Migration apply failed; the new binary remains installed and the previous binary retained at ${backupPath}: ${detail}`);
-    }
-    // Keep the previous binary available until migration apply has completed.
+    // The replacement completed; the temporary rollback copy is no longer needed.
     removeFileBestEffort(backupPath);
     return {
         currentVersion,
@@ -349,19 +316,32 @@ export async function performUpgrade(check, opts, dependencies) {
         installMethod,
         binaryPath: execPath,
         checksumVerified,
-        postUpgrade: runPostUpgradeTasks(execPath, { skip: skipPostUpgrade }),
+        postUpgrade: runPostUpgradeTasks(execPath, { skip: skipPostUpgrade }, dependencies?.upgradeHistoricalStateDatabase ?? upgradeHistoricalStateDatabase),
     };
 }
 /**
- * Rebuild the derived index after the explicit migration command succeeds.
- * Migration and indexing are intentionally separate lifecycle steps.
+ * Rebuild the derived index after a successful upgrade.
  */
-function runPostUpgradeTasks(akmBin, opts) {
+function runPostUpgradeTasks(akmBin, opts, upgradeState) {
+    let stateUpgrade;
+    try {
+        stateUpgrade = upgradeState();
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        return {
+            ok: false,
+            skipped: opts.skip,
+            message: `Upgrade completed, but the state schema was not prepared (${detail}). ` +
+                "Preserve state.db and run `akm upgrade --force` before other AKM commands.",
+        };
+    }
+    const stateNote = stateUpgrade.safetyCopyPath ? ` Historical state safety copy: ${stateUpgrade.safetyCopyPath}.` : "";
     if (opts.skip) {
         return {
             ok: true,
             skipped: true,
-            message: "Migration completed; skipped the index rebuild. Run `akm index` manually to rebuild the index.",
+            message: `Upgrade completed.${stateNote} Skipped the index rebuild. Run \`akm index\` manually to rebuild the index.`,
         };
     }
     try {
@@ -374,7 +354,7 @@ function runPostUpgradeTasks(akmBin, opts) {
             return {
                 ok: false,
                 skipped: false,
-                message: `Migration completed, but the index rebuild could not start: ${result.error.message}. Run \`akm index\` manually.`,
+                message: `Upgrade completed.${stateNote} The index rebuild could not start: ${result.error.message}. Run \`akm index\` manually.`,
             };
         }
         if (result.status !== 0) {
@@ -383,14 +363,14 @@ function runPostUpgradeTasks(akmBin, opts) {
                 ok: false,
                 skipped: false,
                 exitCode: result.status,
-                message: `Migration completed, but post-upgrade \`akm index\` failed (${detail}). Run \`akm index\` manually.`,
+                message: `Upgrade completed.${stateNote} Post-upgrade \`akm index\` failed (${detail}). Run \`akm index\` manually.`,
             };
         }
         return {
             ok: true,
             skipped: false,
             exitCode: 0,
-            message: "Migration completed and the index was rebuilt against the new binary.",
+            message: `Upgrade completed and the index was rebuilt against the new binary.${stateNote}`,
         };
     }
     catch (err) {
@@ -398,21 +378,20 @@ function runPostUpgradeTasks(akmBin, opts) {
         return {
             ok: false,
             skipped: false,
-            message: `Migration completed, but the index rebuild failed: ${detail}. Run \`akm index\` manually.`,
+            message: `Upgrade completed.${stateNote} The index rebuild failed: ${detail}. Run \`akm index\` manually.`,
         };
     }
 }
 /**
- * The package-manager arm of {@link performUpgrade}: preflight → install →
- * post-install version verification → migrate apply → post-upgrade tasks.
+ * The package-manager arm of {@link performUpgrade}: install → post-install
+ * version verification → post-upgrade tasks.
  * Extracted whole so performUpgrade stays under its fn-size baseline.
  */
 function runPackageManagerUpgrade(input) {
-    const { packageManagerCommand, currentVersion, latestVersion, installMethod, migration, skipPostUpgrade } = input;
+    const { packageManagerCommand, currentVersion, latestVersion, installMethod, skipPostUpgrade, upgradeState } = input;
     if (!latestVersion) {
         throw new Error("Unable to determine latest version from GitHub releases. Check https://github.com/itlackey/akm/releases");
     }
-    migration.preflight("akm");
     const result = childProcess.spawnSync(packageManagerCommand.command, packageManagerCommand.args, {
         encoding: "utf8",
         env: process.env,
@@ -429,8 +408,7 @@ function runPackageManagerUpgrade(input) {
     // `latestVersion`: a lagging `@latest` dist-tag (partial publish,
     // registry mirror lag) "succeeds" while leaving the old version on PATH.
     // Re-read the version the shim actually reports before claiming an
-    // upgrade — a confirmed mismatch also means `migrate apply` would run
-    // against the OLD binary, so stop before it.
+    // upgrade, so stop before claiming success.
     const installedVersion = readInstalledCliVersion("akm");
     if (installedVersion !== undefined && installedVersion !== latestVersion) {
         return {
@@ -444,7 +422,6 @@ function runPackageManagerUpgrade(input) {
                 `${packageManagerCommand.displayCommand.replace(/@latest\b/, `@${latestVersion}`)}`,
         };
     }
-    migration.apply("akm");
     return {
         currentVersion,
         newVersion: latestVersion,
@@ -453,7 +430,7 @@ function runPackageManagerUpgrade(input) {
         message: installedVersion === latestVersion
             ? `akm upgraded via ${installMethod} (verified: akm --version reports v${installedVersion})`
             : `akm upgraded via ${installMethod} (installed version could not be verified)`,
-        postUpgrade: runPostUpgradeTasks("akm", { skip: skipPostUpgrade }),
+        postUpgrade: runPostUpgradeTasks("akm", { skip: skipPostUpgrade }, upgradeState),
     };
 }
 /**
@@ -474,27 +451,6 @@ function readInstalledCliVersion(akmBin) {
     const match = (result.stdout ?? "").match(/\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?/);
     return match?.[0];
 }
-function runRequiredCommand(akmBin, args, label) {
-    // A bare "akm" is not spawnable on Windows: npm/pnpm/yarn install a global CLI
-    // as akm.cmd / akm.ps1 shims, and spawnSync without a shell does not apply
-    // PATHEXT — so the package-manager upgrade arm died with ENOENT before it ever
-    // ran. resolveAkmInvocation returns a concrete argv (launcher, runtime + main
-    // script, or a standalone binary) for however this install actually runs.
-    // An explicit path (the standalone arm passes one) is used as given.
-    const [command, ...prefixArgs] = path.isAbsolute(akmBin) ? [akmBin] : resolveAkmInvocation().argv;
-    const result = childProcess.spawnSync(command ?? akmBin, [...prefixArgs, ...args], {
-        encoding: "utf8",
-        env: process.env,
-        stdio: "pipe",
-    });
-    if (result.error) {
-        throw new Error(`${label} could not start: ${result.error.message}`);
-    }
-    if (result.status !== 0) {
-        const detail = (result.stderr ?? "").trim() || (result.stdout ?? "").trim() || `exit code ${result.status}`;
-        throw new Error(`${label} failed (${detail}).`);
-    }
-}
 function removeFileBestEffort(filePath) {
     try {
         fs.unlinkSync(filePath);

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

@@ -26,7 +26,8 @@ export async function akmAdd(input) {
     if (shouldAddAsWebsiteUrl(ref)) {
         return addWebsiteSource(ref, stashDir, input.name, input.options);
     }
-    // Detect local directory refs and route them to stashes[] instead of installed[]
+    // Local directories become filesystem bundles; registry refs use the
+    // registry-backed bundle installer below.
     try {
         const parsed = parseRegistryRef(ref);
         if (parsed.source === "local") {
@@ -38,10 +39,7 @@ export async function akmAdd(input) {
     }
     return addRegistryStash(ref, stashDir, input.writable);
 }
-/**
- * Add a local directory as a filesystem bundle (spec §10.1) — replaces the
- * retired `sources[]` filesystem entry.
- */
+/** Add a local directory as a filesystem bundle. */
 async function addLocalSource(ref, sourcePath, stashDir, explicitName) {
     const stashRoot = detectStashRoot(sourcePath);
     const resolvedPath = path.resolve(stashRoot);

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

@@ -42,13 +42,9 @@ export const upgradeCommand = defineJsonCommand({
         force: { type: "boolean", description: "Force upgrade even if on latest", default: false },
         "skip-post-upgrade": {
             type: "boolean",
-            description: "Skip the post-upgrade index rebuild (migration preflight and apply still run)",
+            description: "Skip the post-upgrade index rebuild",
             default: false,
         },
-        "migration-config": {
-            type: "string",
-            description: "For 0.9+ upgrades, pass an operator-prepared config only to the new binary's migration apply",
-        },
     },
     async run({ args }) {
         const check = await checkForUpdate(pkgVersion);
@@ -57,8 +53,7 @@ export const upgradeCommand = defineJsonCommand({
             return;
         }
         const skipPostUpgrade = args["skip-post-upgrade"];
-        const migrationConfig = args["migration-config"];
-        const result = await performUpgrade(check, { force: args.force, skipPostUpgrade, migrationConfig });
+        const result = await performUpgrade(check, { force: args.force, skipPostUpgrade });
         output("upgrade", result);
     },
 });
@@ -75,14 +70,6 @@ async function runSyncBody(args) {
             writable = resolveWritableOverride(loadConfig());
         }
         const result = saveGitStash(effectiveName, args.message, writable, { push: args.push !== false });
-        // 0.9.0 breaking change: both "save" holdovers from the command's
-        // pre-rename name are now "sync" — the persisted eventType below and the
-        // envelope shape emitted at the end of this function. Historical state.db
-        // rows still carry "save" — `readEvents`/`tailEvents` (src/core/events.ts)
-        // treat "save" and "sync" as synonyms on READ so `akm log --type save`
-        // keeps returning both old and new rows. Only the WRITE side changes here.
-        // The envelope shape needs no such synonym: it is per-invocation, never
-        // persisted, so nothing can be holding an old value.
         appendEvent({
             eventType: "sync",
             metadata: {