akm-cli 0.9.8 → 0.9.9

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

@@ -7,10 +7,11 @@ 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 { resolveNpmGlobalRoot } from "../../tasks/resolve-akm-bin.js";
+import { runMigrationTool } from "../migration-tool.js";
 const REPO = "itlackey/akm";
 const DEFAULT_PACKAGE_NAME = "akm-cli";
 const NODE_MODULES_SEGMENT = "/node_modules/";
@@ -91,8 +92,37 @@ export function getInstallSignals() {
         bunMain: mainPath,
         importMetaDir: getDirname(import.meta.url),
         hasAkmVersion: typeof AKM_VERSION !== "undefined",
+        npmGlobalRoot: resolveNpmGlobalRootForThisProcess(),
     };
 }
+function resolveNpmGlobalRootForThisProcess() {
+    const nodePath = process.env.AKM_LAUNCHER_NODE?.trim() || (process.versions.bun ? undefined : process.execPath);
+    if (!nodePath)
+        return undefined;
+    try {
+        return resolveNpmGlobalRoot(nodePath, process.env);
+    }
+    catch {
+        return undefined;
+    }
+}
+function isUnderDirectory(dir, root) {
+    const real = (value) => {
+        try {
+            return fs.realpathSync(value);
+        }
+        catch {
+            return path.resolve(value);
+        }
+    };
+    const relative = path.relative(real(root), real(dir));
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+/** The package that depends on this akm: the directory holding the `node_modules` it lives in. */
+function packageLocalRoot(importMetaDir) {
+    const index = normalizePathSeparators(importMetaDir).lastIndexOf(NODE_MODULES_SEGMENT);
+    return index < 0 ? importMetaDir : importMetaDir.slice(0, index);
+}
 // AKM_VERSION ambient type is declared in globals.d.ts
 export function detectInstallMethod(signals) {
     const s = signals ?? getInstallSignals();
@@ -104,6 +134,14 @@ export function detectInstallMethod(signals) {
         if (PNPM_GLOBAL_INSTALL_PATTERN.test(normalizedImportMetaDir)) {
             return "pnpm";
         }
+        // A node_modules install outside the npm global root is a DEPENDENCY of
+        // some other package (an image's tools dir, a plugin's node_modules):
+        // it moves when that package does, and an `npm install -g` here would
+        // "succeed" while the parent kept executing its own copy. Only a proven
+        // global root can make that call; without one this stays "npm".
+        if (s.npmGlobalRoot && s.importMetaDir && !isUnderDirectory(s.importMetaDir, s.npmGlobalRoot)) {
+            return "package-local";
+        }
         return "npm";
     }
     // Bun-compiled binaries: mainPath points to a virtual /$bunfs/
@@ -172,7 +210,23 @@ export async function performUpgrade(check, opts, dependencies) {
     const { currentVersion, latestVersion, installMethod } = check;
     const force = opts?.force === true;
     const skipPostUpgrade = opts?.skipPostUpgrade === true;
-    // All install methods can short-circuit here unless the user explicitly forces an upgrade.
+    const runTool = dependencies?.runMigrationTool ?? runMigrationTool;
+    // Every `akm upgrade` ends by running `akm-migrate apply`, install or no
+    // install: the migrator on disk after the install step is the one whose
+    // migrations the installed akm needs, and an image that ships akm has
+    // nothing to install and nobody to run a migration by hand (#895). The two
+    // no-install cases return here.
+    if (installMethod === "package-local") {
+        const parent = packageLocalRoot(getInstallSignals().importMetaDir ?? "");
+        return {
+            currentVersion,
+            newVersion: latestVersion,
+            upgraded: false,
+            installMethod,
+            message: `akm runs as a dependency of the package at ${parent}; upgrade that package to move akm.`,
+            migration: await runMigrationStep(runTool),
+        };
+    }
     if (!check.updateAvailable && !force) {
         return {
             currentVersion,
@@ -180,6 +234,7 @@ export async function performUpgrade(check, opts, dependencies) {
             upgraded: false,
             installMethod,
             message: `akm v${currentVersion} is already the latest version`,
+            migration: await runMigrationStep(runTool),
         };
     }
     const packageManagerCommand = getPackageManagerUpgradeCommand(installMethod);
@@ -190,7 +245,7 @@ export async function performUpgrade(check, opts, dependencies) {
             latestVersion,
             installMethod,
             skipPostUpgrade,
-            upgradeState: dependencies?.upgradeHistoricalStateDatabase ?? upgradeHistoricalStateDatabase,
+            runTool,
         });
     }
     if (installMethod === "unknown") {
@@ -200,6 +255,7 @@ export async function performUpgrade(check, opts, dependencies) {
             upgraded: false,
             installMethod,
             message: `Unable to detect install method. Upgrade manually from https://github.com/${REPO}/releases`,
+            migration: await runMigrationStep(runTool),
         };
     }
     // Binary install
@@ -309,6 +365,8 @@ export async function performUpgrade(check, opts, dependencies) {
     }
     // The replacement completed; the temporary rollback copy is no longer needed.
     removeFileBestEffort(backupPath);
+    // The new binary is at execPath now, so this re-execs the NEW migrator.
+    const migration = await runMigrationStep(runTool);
     return {
         currentVersion,
         newVersion: latestVersion,
@@ -316,32 +374,46 @@ export async function performUpgrade(check, opts, dependencies) {
         installMethod,
         binaryPath: execPath,
         checksumVerified,
-        postUpgrade: runPostUpgradeTasks(execPath, { skip: skipPostUpgrade }, dependencies?.upgradeHistoricalStateDatabase ?? upgradeHistoricalStateDatabase),
+        migration,
+        postUpgrade: runPostUpgradeTasks(execPath, { skip: skipPostUpgrade }),
     };
 }
 /**
- * Rebuild the derived index after a successful upgrade.
+ * `akm-migrate apply`, spawned so it is whichever migrator is on disk NOW:
+ * after a successful install, the new one. Its JSON plan becomes the
+ * response's `migration`. A migrator that could not run or print a plan
+ * reports `failed` with its error text instead of throwing, so the install
+ * outcome the caller is about to report is never lost behind it.
  */
-function runPostUpgradeTasks(akmBin, opts, upgradeState) {
-    let stateUpgrade;
+async function runMigrationStep(runTool) {
+    let result;
     try {
-        stateUpgrade = upgradeState();
+        result = await runTool(["apply"]);
     }
     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 --state-only` before other AKM commands (the binary is already current).",
-        };
+        return { status: "failed", error: error instanceof Error ? error.message : String(error) };
+    }
+    const line = result.stdout.trim();
+    try {
+        const plan = JSON.parse(line);
+        if (plan.status === "current" || plan.status === "ready" || plan.status === "blocked") {
+            return plan;
+        }
     }
-    const stateNote = stateUpgrade.safetyCopyPath ? ` Historical state safety copy: ${stateUpgrade.safetyCopyPath}.` : "";
+    catch {
+        // Not a plan; reported below with whatever the migrator did say.
+    }
+    return { status: "failed", error: result.stderr.trim() || line || `akm-migrate exited ${result.status}` };
+}
+/**
+ * Rebuild the derived index after a successful upgrade.
+ */
+function runPostUpgradeTasks(akmBin, opts) {
     if (opts.skip) {
         return {
             ok: true,
             skipped: true,
-            message: `Upgrade completed.${stateNote} Skipped the index rebuild. Run \`akm index\` manually to rebuild the index.`,
+            message: "Upgrade completed. Skipped the index rebuild. Run `akm index` manually to rebuild the index.",
         };
     }
     try {
@@ -354,7 +426,7 @@ function runPostUpgradeTasks(akmBin, opts, upgradeState) {
             return {
                 ok: false,
                 skipped: false,
-                message: `Upgrade completed.${stateNote} The index rebuild could not start: ${result.error.message}. Run \`akm index\` manually.`,
+                message: `Upgrade completed. The index rebuild could not start: ${result.error.message}. Run \`akm index\` manually.`,
             };
         }
         if (result.status !== 0) {
@@ -363,14 +435,14 @@ function runPostUpgradeTasks(akmBin, opts, upgradeState) {
                 ok: false,
                 skipped: false,
                 exitCode: result.status,
-                message: `Upgrade completed.${stateNote} Post-upgrade \`akm index\` failed (${detail}). Run \`akm index\` manually.`,
+                message: `Upgrade completed. Post-upgrade \`akm index\` failed (${detail}). Run \`akm index\` manually.`,
             };
         }
         return {
             ok: true,
             skipped: false,
             exitCode: 0,
-            message: `Upgrade completed and the index was rebuilt against the new binary.${stateNote}`,
+            message: "Upgrade completed and the index was rebuilt against the new binary.",
         };
     }
     catch (err) {
@@ -378,7 +450,7 @@ function runPostUpgradeTasks(akmBin, opts, upgradeState) {
         return {
             ok: false,
             skipped: false,
-            message: `Upgrade completed.${stateNote} The index rebuild failed: ${detail}. Run \`akm index\` manually.`,
+            message: `Upgrade completed. The index rebuild failed: ${detail}. Run \`akm index\` manually.`,
         };
     }
 }
@@ -387,8 +459,8 @@ function runPostUpgradeTasks(akmBin, opts, upgradeState) {
  * version verification → post-upgrade tasks.
  * Extracted whole so performUpgrade stays under its fn-size baseline.
  */
-function runPackageManagerUpgrade(input) {
-    const { packageManagerCommand, currentVersion, latestVersion, installMethod, skipPostUpgrade, upgradeState } = input;
+async function runPackageManagerUpgrade(input) {
+    const { packageManagerCommand, currentVersion, latestVersion, installMethod, skipPostUpgrade, runTool } = input;
     if (!latestVersion) {
         throw new Error("Unable to determine latest version from GitHub releases. Check https://github.com/itlackey/akm/releases");
     }
@@ -402,7 +474,12 @@ function runPackageManagerUpgrade(input) {
     }
     if (result.status !== 0) {
         const details = (result.stderr ?? "").trim() || (result.stdout ?? "").trim() || `exit code ${result.status}`;
-        throw new Error(`Failed to upgrade akm via ${installMethod}: ${details}\nRun manually: ${packageManagerCommand.displayCommand}`);
+        // The install could not change what runs, so the migrator on disk is
+        // still the right one: run it, then say so, or an operator reading the
+        // EACCES will assume the migration is stuck behind it (#895).
+        const migration = await runMigrationStep(runTool);
+        throw new Error(`Failed to upgrade akm via ${installMethod}: ${details}\nRun manually: ${packageManagerCommand.displayCommand}\n` +
+            `Pending migrations ran anyway (status: ${migration.status}).`);
     }
     // The package manager exiting 0 does not prove it delivered
     // `latestVersion`: a lagging `@latest` dist-tag (partial publish,
@@ -420,6 +497,7 @@ function runPackageManagerUpgrade(input) {
                 `v${installedVersion} (expected v${latestVersion}). The ${installMethod} registry's @latest tag ` +
                 `may be lagging the GitHub release — try again shortly, or install the exact version: ` +
                 `${packageManagerCommand.displayCommand.replace(/@latest\b/, `@${latestVersion}`)}`,
+            migration: await runMigrationStep(runTool),
         };
     }
     return {
@@ -430,7 +508,8 @@ 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 }, upgradeState),
+        migration: await runMigrationStep(runTool),
+        postUpgrade: runPostUpgradeTasks("akm", { skip: skipPostUpgrade }),
     };
 }
 /**
@@ -520,40 +599,3 @@ export function getPackageManagerUpgradeCommand(installMethod, packageName = get
     }
     return undefined;
 }
-/**
- * Apply pending historical destructive state.db migrations WITHOUT installing a
- * new akm — the body of `akm upgrade --state-only`.
- *
- * Migrations flagged `historical-destructive` are refused during an ordinary
- * managed open: they need a verified sibling safety copy taken under the
- * migration writer lock, and that is deliberate, so an unattended `akm index`
- * can never quietly drop operator state.
- *
- * The bug this fixes is not the guard but its reachability (#895). The only
- * code path that set `allowHistoricalDestructiveStateUpgrade` ran as a
- * POST-INSTALL step of a real upgrade, so it sat behind an npm install. Where
- * akm is installed globally by an image and the runtime user is unprivileged,
- * that install fails EACCES and throws long before the migration is reached —
- * leaving the documented remedy impossible to run and `akm index --full`
- * permanently blocked. Nothing about the migration itself needs the network,
- * root, or a new binary; it is local, offline, and already verified.
- *
- * The safety copy is NOT skipped here. This changes only who may ask for the
- * migration, never what it does.
- */
-export function upgradeStateOnly(currentVersion, dependencies) {
-    const upgradeState = dependencies?.upgradeHistoricalStateDatabase ?? upgradeHistoricalStateDatabase;
-    const result = upgradeState();
-    return {
-        currentVersion,
-        newVersion: currentVersion,
-        upgraded: false,
-        installMethod: detectInstallMethod(),
-        message: result.upgraded
-            ? `Applied pending state.db migrations. Safety copy: ${result.safetyCopyPath}`
-            : "state.db is already current; no migration was needed",
-        stateUpgrade: result.safetyCopyPath
-            ? { applied: result.upgraded, safetyCopyPath: result.safetyCopyPath }
-            : { applied: result.upgraded },
-    };
-}

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

@@ -31,7 +31,7 @@ export async function akmAdd(input) {
     try {
         const parsed = parseRegistryRef(ref);
         if (parsed.source === "local") {
-            return addLocalSource(ref, parsed.sourcePath, stashDir, input.name);
+            return addLocalSource(ref, parsed.sourcePath, stashDir, input.name, input.adapter);
         }
     }
     catch {
@@ -40,22 +40,23 @@ export async function akmAdd(input) {
     return addRegistryStash(ref, stashDir, input.writable);
 }
 /** Add a local directory as a filesystem bundle. */
-async function addLocalSource(ref, sourcePath, stashDir, explicitName) {
+async function addLocalSource(ref, sourcePath, stashDir, explicitName, explicitAdapter) {
     const stashRoot = detectStashRoot(sourcePath);
     const resolvedPath = path.resolve(stashRoot);
+    const adapter = explicitAdapter ?? detectAdapterId(resolvedPath);
     let bundleKey = explicitName ?? toReadableId(resolvedPath);
     mutateConfig((config) => {
         const existing = bundleKeyForPath(config, resolvedPath);
         if (existing) {
             bundleKey = existing;
             const current = config.bundles?.[existing];
-            if (current?.components)
+            if (current?.components && explicitAdapter === undefined)
                 return config;
             const bundles = { ...(config.bundles ?? {}) };
             bundles[existing] = {
                 ...current,
                 path: resolvedPath,
-                components: { main: { root: ".", adapter: detectAdapterId(resolvedPath) } },
+                components: { main: { root: ".", adapter } },
             };
             return { ...config, bundles };
         }
@@ -63,7 +64,7 @@ async function addLocalSource(ref, sourcePath, stashDir, explicitName) {
         bundleKey = nextBundleKey(bundles, explicitName, resolvedPath);
         bundles[bundleKey] = {
             path: resolvedPath,
-            components: { main: { root: ".", adapter: detectAdapterId(resolvedPath) } },
+            components: { main: { root: ".", adapter } },
         };
         return { ...config, bundles };
     });

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

@@ -27,13 +27,13 @@
  */
 import { defineCommand } from "citty";
 import { getParsedInvocation } from "../../cli/invocation.js";
-import { defineJsonCommand, GLOBAL_OUTPUT_ARGS, output, runWithJsonErrors } from "../../cli/shared.js";
+import { defineJsonCommand, EXIT_CODES, GLOBAL_OUTPUT_ARGS, output, runWithJsonErrors } from "../../cli/shared.js";
 import { loadConfig } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { resolveWritableOverride, saveGitStash } from "../../sources/providers/git.js";
 import { pkgVersion } from "../../version.js";
-import { checkForUpdate, performUpgrade, upgradeStateOnly } from "./self-update.js";
+import { checkForUpdate, performUpgrade } from "./self-update.js";
 import { akmClone } from "./source-clone.js";
 export const upgradeCommand = defineJsonCommand({
     meta: { name: "upgrade", description: "Upgrade akm to the latest release" },
@@ -45,24 +45,8 @@ export const upgradeCommand = defineJsonCommand({
             description: "Skip the post-upgrade index rebuild",
             default: false,
         },
-        "state-only": {
-            type: "boolean",
-            description: "Apply pending state.db migrations without installing a new akm",
-            default: false,
-        },
     },
     async run({ args }) {
-        // Applying a historical destructive state migration used to be reachable
-        // ONLY as a post-install step of a real upgrade, so an install akm cannot
-        // rewrite -- a global npm install owned by root, an image that ships the
-        // CLI -- had no route to it at all: the npm step fails EACCES and throws
-        // long before the migration runs (#895). The migration is a local,
-        // offline, already-verified operation; it does not need the network or a
-        // new binary, and coupling it to one was the bug.
-        if (args["state-only"]) {
-            output("upgrade", upgradeStateOnly(pkgVersion));
-            return;
-        }
         const check = await checkForUpdate(pkgVersion);
         if (args.check) {
             output("upgrade", check);
@@ -71,6 +55,11 @@ export const upgradeCommand = defineJsonCommand({
         const skipPostUpgrade = args["skip-post-upgrade"];
         const result = await performUpgrade(check, { force: args.force, skipPostUpgrade });
         output("upgrade", result);
+        // The install may have succeeded, but an upgrade whose migration is
+        // blocked or could not run is not done: exit like `akm migrate apply` does.
+        if (result.migration?.status === "blocked" || result.migration?.status === "failed") {
+            process.exitCode = EXIT_CODES.GENERAL;
+        }
     },
 });
 // `sync` body, standalone so the git-commit/push logic stays in one place.

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

@@ -349,10 +349,11 @@ const tasksSyncCommand = defineJsonCommand({
         const result = await akmTasksSync({}, args.bundle, { rebind });
         output("task-sync", result);
         // #867: sync degrades — sources that failed to parse/prepare are
-        // excluded from reconciliation and reported in `result.failed` rather
+        // excluded from reconciliation and reported in `result.failures` rather
         // than poisoning the whole sync, but their presence must still fail
-        // the command's exit code so the breakage stays visible.
-        if (result.failed.length > 0)
+        // the command's exit code so the breakage stays visible. (#906: this key
+        // matches the `--dry-run` preview's `failures` field — no separate name.)
+        if (result.failures.length > 0)
             process.exitCode = EXIT_CODES.GENERAL;
     },
 });

package/dist/commands/tasks/tasks.js

@@ -391,7 +391,7 @@ async function buildSchedulerSyncPlan(deps, bundleTarget, options) {
     const expectedSignature = sched.expectedSignature?.bind(sched);
     const needsRuntime = preflight.operations.some((operation) => operation.kind !== "remove" && operation.options?.binding === undefined);
     const prepared = needsRuntime
-        ? prepareSchedulerSyncRuntime(syncTarget ? { target: syncTarget } : undefined, deps, options.rebind === true, "reconcile native scheduler bindings", warnings)
+        ? prepareSchedulerSyncRuntime(syncTarget ? { target: syncTarget } : undefined, deps, options.rebind === true, "reconcile native scheduler bindings", warnings, allEntries.map((entry) => entry.binding))
         : undefined;
     const plan = finalizeSchedulerSyncPlan({
         ...common,
@@ -416,7 +416,7 @@ export async function akmTasksSync(deps = {}, bundleTarget, options = {}) {
         unchanged: [...plan.unchanged],
         skipped: [],
         backend: sched.name,
-        failed: plan.failures.map((failure) => ({ ...failure })),
+        failures: plan.failures.map((failure) => ({ ...failure })),
         ...(warnings.length > 0 ? { warnings } : {}),
     };
 }
@@ -841,16 +841,16 @@ async function prepareTaskAddSchedulerTransaction(input) {
         publishOperationIndex: removals.length,
     });
 }
-function prepareSchedulerSyncRuntime(base, deps, explicitRebind, operation, warnings) {
+function prepareSchedulerSyncRuntime(base, deps, explicitRebind, operation, warnings, installedBindings = []) {
     if (deps.backend && !deps.schedulerRuntime)
         return base ? { options: base } : {};
     if (deps.schedulerRuntime) {
         const runtime = deps.schedulerRuntime();
-        warnIneligibleRebind(runtime, explicitRebind, warnings);
+        warnIneligibleRebind(runtime, explicitRebind, warnings, installedBindings);
         return { options: { ...base, binding: runtime.binding, contextPath: runtime.contextPath } };
     }
     const invocation = resolveAndValidateSchedulerInvocation(explicitRebind, operation);
-    warnIneligibleRebind(invocation, explicitRebind, warnings);
+    warnIneligibleRebind(invocation, explicitRebind, warnings, installedBindings);
     const descriptor = schedulerContextDescriptor();
     const contextPath = schedulerContextPath(descriptor);
     return {
@@ -870,9 +870,16 @@ function resolveAndValidateSchedulerInvocation(explicitRebind, operation) {
     }
     return { binding: invocation.argv, contextPath: "", eligible: invocation.eligible, kind: invocation.kind };
 }
-function warnIneligibleRebind(runtime, explicitRebind, warnings) {
+function warnIneligibleRebind(runtime, explicitRebind, warnings, installedBindings) {
     if (!explicitRebind || runtime.eligible !== false || warnings.length > 0)
         return;
+    // #868 residue: a `--rebind` that binds every currently-installed
+    // entry to the SAME invocation it already carries changes nothing — this
+    // is the steady state of an image-baked install re-running `task sync
+    // --rebind` on a timer. Only warn when the rebind actually moves an entry
+    // to a different invocation.
+    if (installedBindings.length > 0 && installedBindings.every((bound) => sameArgv(bound, runtime.binding)))
+        return;
     warnings.push(`--rebind bound scheduled tasks to an ineligible ${runtime.kind ?? "unknown"} invocation (${runtime.binding.join(" ")}); scheduled runs will invoke a mutable, unproven binary. Install akm via \`npm install --global akm-cli\` or a standalone release, then re-run \`akm task sync --rebind\`.`);
 }
 function groupInstalledBindings(entries, invocation) {

package/dist/core/adapter/adapter-ids.js

@@ -0,0 +1,35 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Dependency-free adapter-id table (#909) — mirrors
+ * `src/integrations/harnesses/ids.ts`'s split from its own heavy barrel.
+ *
+ * `core/config/schema/sources-bundles.ts` needs one small, DATA-shaped fact
+ * about the adapter registry: the canonical ordered id list, to validate
+ * `components.*.adapter` and to reject a typo instead of silently falling
+ * back to `akm` (#909). Importing `./registry.ts` (`BUILTIN_ADAPTERS`) for
+ * that would pull in all 11 concrete adapters and, transitively, the indexer
+ * modules they delegate to (`indexer/passes/metadata`, `core/asset/*`, …) —
+ * weight a config-schema module has no reason to carry just to validate one
+ * enum. This table is the canonical, dependency-free MIRROR of the id list;
+ * `./adapters/index.ts`'s `BUILTIN_ADAPTERS` construction asserts its ids
+ * match this table (order included) at module-load time, so the two can
+ * never silently drift without a loud failure.
+ */
+/** Canonical, ordered list of valid adapter ids (matches `BUILTIN_ADAPTERS` order). */
+export const ADAPTER_ID_TABLE = [
+    "website-snapshot",
+    "agent-skills",
+    "claude",
+    "opencode",
+    "dotenv",
+    "akm-workflow",
+    "akm-task",
+    "llm-wiki",
+    "akm",
+    "okf",
+    "generic-files",
+];
+/** The dependency-free counterpart of `./registry.ts`'s `getAdapters().map(a => a.id)`. */
+export const VALID_ADAPTER_IDS = ADAPTER_ID_TABLE;

package/dist/core/adapter/adapters/index.js

@@ -1,6 +1,21 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Built-in `BundleAdapter` barrel + the static, frozen `BUILTIN_ADAPTERS` list
+ * (normative §12.6) — akm 0.9.0 chunk-2 (WI-A) + the format-family work item
+ * (#46).
+ *
+ * `BUILTIN_ADAPTERS` is the ordered built-in adapter set the registry
+ * (`../registry`) exposes via `getAdapters()` / `adapterForId()`. It is a
+ * plain frozen array populated at MODULE LOAD — there is no mutable
+ * registration step and no load-order dependency, so no production call site
+ * (`installations.ts#detectAdapterId`, `provider-utils.ts#detectStashRoot`)
+ * depends on anyone first calling a registration function (normative §12.6 —
+ * "static frozen `BUILTIN_ADAPTERS` map"). The earlier mutable
+ * `registerAdapter` singleton that this replaced is retired.
+ */
+import { ADAPTER_ID_TABLE } from "../adapter-ids.js";
 import { agentSkillsAdapter } from "./agent-skills-adapter.js";
 import { akmAdapter } from "./akm-adapter.js";
 import { akmTaskAdapter } from "./akm-task-adapter.js";
@@ -69,3 +84,17 @@ export const BUILTIN_ADAPTERS = Object.freeze([
     // Explicit-config fallback (never auto-selected) — last.
     genericFilesAdapter,
 ]);
+// Construction-time drift guard (#909): ../adapter-ids.ts's ADAPTER_ID_TABLE
+// is config's dependency-free mirror of this list, kept out of core/config's
+// import graph so config doesn't have to import this (heavier) barrel. Assert
+// they match so the mirror can never silently drift — a new/reordered/renamed
+// adapter that forgets to update adapter-ids.ts fails loudly here instead of
+// quietly breaking config's `components.*.adapter` validation.
+{
+    const actualIds = BUILTIN_ADAPTERS.map((a) => a.id);
+    const expectedIds = [...ADAPTER_ID_TABLE];
+    if (actualIds.length !== expectedIds.length || actualIds.some((id, i) => id !== expectedIds[i])) {
+        throw new Error(`adapter-ids.ts ADAPTER_ID_TABLE (${expectedIds.join(", ")}) does not match ` +
+            `BUILTIN_ADAPTERS (${actualIds.join(", ")}) — update adapter-ids.ts to match.`);
+    }
+}

package/dist/core/adapter/detect-adapter.js

@@ -1,13 +1,101 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import { getAdapters } from "./registry.js";
-/** Select the first built-in adapter whose ordered root probe claims `root`. */
+import fs from "node:fs";
+import path from "node:path";
+import { adapterForId, getAdapters } from "./registry.js";
+/**
+ * Tool-dir-shaped adapters (#908): their install-time probe recognizes only a
+ * BOUNDED slice of the root — `claude`/`opencode`'s own `commands`/`agents`/
+ * `skills` tool dirs, or `agent-skills`' own `<name>/SKILL.md` packages. A
+ * bundle that ALSO carries ordinary akm content (`knowledge/`, `workflows/`,
+ * a stray `content/` folder of Markdown, …) alongside one of these layouts had
+ * that content SILENTLY dropped: the narrow adapter won the ordered probe and
+ * indexed only its own three-dir slice, with no warning that anything else
+ * was there (issue #908 — 73 documents disappeared from one real bundle).
+ *
+ * `okf` / `llm-wiki` / `dotenv` / `website-snapshot` / `akm-workflow` /
+ * `akm-task` are deliberately NOT in this set: each carries its own tight,
+ * disjoint marker (a root index document, `schema.md`+`pages/`, an env/secrets-only
+ * layout, `manifest.json`, a workflow/task-shaped top-level file) that is not
+ * at risk of firing merely because a FEW directory names happen to overlap
+ * with akm's own stash subdirs — narrowing the fix to the three families the
+ * issue is actually about keeps this from touching adapters it was never
+ * about.
+ */
+const SHADOWABLE_ADAPTER_IDS = new Set(["agent-skills", "claude", "opencode"]);
+/**
+ * True when `root` — already claimed by `winnerId` (one of
+ * {@link SHADOWABLE_ADAPTER_IDS}) — ALSO carries a top-level directory the
+ * `akm` adapter's own probe recognizes as its workspace shape (spec §1.2) and
+ * that `winnerId` does not own (its `directoryList()`, or — for `agent-skills`,
+ * which owns no fixed directory names — a root-level `<name>/SKILL.md`
+ * package) but which holds at least one real file. Cheap by design: only
+ * shallow `readdirSync` calls, one level into each candidate top-level dir —
+ * no recursive walk, no file content read, no git spawn — so this never adds
+ * meaningful cost to the install-time probe it augments.
+ */
+function hasExtraAkmContent(root, winnerId) {
+    const akm = adapterForId("akm");
+    if (akm?.looksLikeRoot?.(root) !== true)
+        return false;
+    const winner = adapterForId(winnerId);
+    const stubComponent = { id: "detect", adapter: winnerId, root, writable: false };
+    const ownedDirs = new Set(winner?.directoryList?.(stubComponent) ?? []);
+    let entries;
+    try {
+        entries = fs.readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return false;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name.startsWith("."))
+            continue;
+        if (ownedDirs.has(entry.name))
+            continue;
+        if (winnerId === "agent-skills") {
+            // A root-level `<name>/SKILL.md` package IS agent-skills' own recognized
+            // surface even though it has no fixed directoryList — not "extra" content.
+            try {
+                if (fs.statSync(path.join(root, entry.name, "SKILL.md")).isFile())
+                    continue;
+            }
+            catch {
+                // Not a skill package — fall through to the candidate-file check below.
+            }
+        }
+        let children;
+        try {
+            children = fs.readdirSync(path.join(root, entry.name), { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        if (children.some((child) => child.isFile() && !child.name.startsWith(".")))
+            return true;
+    }
+    return false;
+}
+/**
+ * Select the first built-in adapter whose ordered root probe claims `root`.
+ *
+ * A mixed-layout bundle (#908) that both a tool-dir-shaped adapter AND the
+ * `akm` adapter would claim detects as `akm` — the superset, which still
+ * indexes the narrower layout's own files correctly (`agent-skills`'
+ * `<name>/SKILL.md` packages, `claude`/`opencode`'s `commands`/`agents`/
+ * `skills`) while also picking up whatever else is in the bundle. A bundle
+ * that carries ONLY the narrow layout (no extra content) is unaffected.
+ */
 export function detectAdapterId(root, fallback = "akm") {
     for (const adapter of getAdapters()) {
         try {
-            if (adapter.looksLikeRoot?.(root) === true)
+            if (adapter.looksLikeRoot?.(root) === true) {
+                if (SHADOWABLE_ADAPTER_IDS.has(adapter.id) && hasExtraAkmContent(root, adapter.id)) {
+                    return "akm";
+                }
                 return adapter.id;
+            }
         }
         catch {
             // An unreadable or racing probe does not claim the bundle.