akm-cli 0.9.17-alpha.4 → 0.9.17-alpha.5

package/CHANGELOG.md

@@ -6,6 +6,36 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.17-alpha.5] - 2026-09-27
+
+`akm show` works again for a memory that has a `.derived.md` child (835 of them
+in one real bundle), and `akm bundle add --provider … --name` holds to the same
+`--name` contract as every other add.
+
+### Fixed
+
+- **`akm show` works for a memory that has a `.derived.md` child.** When
+  `memories/X.md` and `memories/X.derived.md` both existed, `akm show
+  memories/X`, with or without a `#fragment`, failed with
+  `RESOURCE_ALREADY_EXISTS` ("multiple physical owners"); `akm curate`
+  previewed such a memory from its description alone, and `akm curate --pack`
+  left it out. The index gives the derived child its own ref,
+  `memories/X.derived`, but the ref lookup also counted `X.derived.md` as a
+  file for `memories/X`. The lookup now follows the index: `memories/X` is
+  `X.md` and `memories/X.derived` is `X.derived.md`. A derived child whose
+  parent file is gone no longer answers for the parent's ref either, so it
+  cannot hide a real `X.md` in a lower-priority bundle. `akm lint` and
+  `--xref` / `--supersedes` validation still accept a ref to `memories/X`
+  when only `X.derived.md` remains. Broken since 0.9.7.
+  (`src/core/asset/asset-placement.ts`, `src/commands/lint/base-linter.ts`)
+- **`akm bundle add --provider … --name` keeps the `--name` contract too.**
+  Since 0.9.17-alpha.4 an explicit `--name` that is not a legal bundle slug,
+  or is taken by another bundle, fails with exit 2, and re-adding a source
+  under a different name points at `akm bundle rename`. A declarative add
+  (`akm bundle add <target> --provider npm|git|website`) still replaced such
+  a name with a derived one and exited 0. It now fails the same way, before
+  any write. (`src/commands/sources/source-manage.ts`)
+
 ## [0.9.17-alpha.4] - 2026-09-27
 
 Search and curate are rebuilt on measured evidence. On a 221-query suite of real
@@ -640,9 +670,8 @@ config migration, and it lands with fewer lines in `src/` than 0.9.17-alpha.3.
   documented for `registryId`. The key used to come from the basename of the
   cache directory the package was unpacked into, which is always `extracted`,
   so every registry bundle after the first was `extracted-<hash>`. A dotted
-  or mixed-case name is slugged like a directory name (`Foo.js` → `foo-js`),
-  and a `--name` that is not a legal bundle slug now falls back to this name
-  too. Bundles that are already installed keep their current key, including
+  or mixed-case name is slugged like a directory name (`Foo.js` → `foo-js`).
+  Bundles that are already installed keep their current key, including
   `extracted`, because every recorded `extracted//…` ref depends on it.
 - **A one-file change in a large directory no longer costs `akm index` half
   an hour.** Both full-text tables keyed their per-entry deletes on

package/dist/commands/lint/base-linter.js

@@ -42,6 +42,7 @@ import { isArchivedRelPath } from "../../core/asset/memory-archive.js";
 import { conceptIdFromTypeName, typeNameFromConceptId } from "../../core/asset/resolve-ref.js";
 import { localDateStamp } from "../../core/common.js";
 import { containsRedactedContent, REDACTED_CONTENT_MARKER } from "../../core/content-safety.js";
+import { DERIVED_SUFFIX } from "../../core/recognition-util.js";
 import { findFenceRegions } from "./markdown-insertion.js";
 // ── Helpers ───────────────────────────────────────────────────────────────────
 /** Fold physically wrapped prose the same way a YAML plain scalar does. */
@@ -216,10 +217,23 @@ export function refExistsInAnyStash(relPath, refType, refName, stashRoots) {
     // record while leaving the live stash untouched.
     return memoryArchiveHasRef(refType, refName, stashRoots);
 }
+/**
+ * The stash-relative files that satisfy a ref, in preference order: its own
+ * placement spellings, then, for a memory, the `<name>.derived.md` child (#882),
+ * so an edge to a parent whose plain `.md` is gone still reaches the child it was
+ * distilled into. This is lint's reachability rule only; the child owns
+ * `memories/<name>.derived`, never `memories/<name>`.
+ */
+function refPathCandidates(refType, typeDir, refName) {
+    const candidates = assetPathCandidatesForName(refType, typeDir, refName);
+    if (refType !== "memory" || refName.endsWith(DERIVED_SUFFIX))
+        return candidates;
+    return [...candidates, assetPathForName(refType, typeDir, `${refName}${DERIVED_SUFFIX}`)];
+}
 /**
  * True when `(refType, refName)` names a memory that prune archived in any
  * root. Mirrors `resolveRefPathInStash`'s candidate set so a ref that resolved
- * through the `.derived.md` twin (#882) still resolves once archived.
+ * through the `.derived.md` child (#882) still resolves once archived.
  */
 function memoryArchiveHasRef(refType, refName, stashRoots) {
     if (refType !== "memory")
@@ -227,7 +241,7 @@ function memoryArchiveHasRef(refType, refName, stashRoots) {
     const typeDir = stashDirFor(refType);
     if (typeDir === undefined)
         return false;
-    const candidates = assetPathCandidatesForName(refType, typeDir, refName);
+    const candidates = refPathCandidates(refType, typeDir, refName);
     for (const root of stashRoots) {
         for (const candidate of candidates) {
             if (isArchivedRelPath(candidate, root))
@@ -241,8 +255,8 @@ function memoryArchiveHasRef(refType, refName, stashRoots) {
  * the same reachability rules (in the same order) as
  * {@link refExistsInAnyStash}, which delegates here. Returns the absolute path
  * of the file that makes the ref "exist" — for a multi-file skill directory
- * that is its `SKILL.md` primary, for a `memory` ref its `.derived.md` twin
- * when the plain `.md` is absent (#882, see `assetPathCandidatesForName`) —
+ * that is its `SKILL.md` primary, for a `memory` ref its `.derived.md` child
+ * when the plain `.md` is absent (#882, see {@link refPathCandidates}) —
  * or `null` when the ref does not resolve in this root.
  *
  * Extracted for SPEC-5 (`--supersedes` demotion): write commands need the
@@ -253,7 +267,7 @@ function memoryArchiveHasRef(refType, refName, stashRoots) {
  */
 export function resolveRefPathInStash(relPath, refType, refName, root) {
     const typeDir = stashDirFor(refType);
-    const candidates = typeDir === undefined ? [relPath] : assetPathCandidatesForName(refType, typeDir, refName);
+    const candidates = typeDir === undefined ? [relPath] : refPathCandidates(refType, typeDir, refName);
     for (const candidate of candidates) {
         const absPath = path.join(root, candidate);
         if (fs.existsSync(absPath))

package/dist/commands/sources/bundle-config-ops.js

@@ -93,12 +93,9 @@ export function bundleKeyForUrl(config, url) {
  * (path/url) — the shared {@link deriveBundleId} rule (D-R5), made unique against
  * the currently-configured bundle keys.
  *
- * This helper stays forgiving (no `--name` contract enforcement): it is also
- * used by `akm source add` (`source-manage.ts`'s `addStash`), which predates
- * and is not in scope for the D6 `--name` contract. A caller that DOES need
- * the D6 contract (an illegal or already-taken explicit name failing loudly)
- * validates with {@link validateExplicitBundleName} itself before calling in,
- * as `source-add.ts`'s local/website/registry add paths do.
+ * Every add path validates an explicit `--name` with
+ * {@link validateExplicitBundleName} before calling in (an illegal or taken
+ * name fails loudly), so a `preferredName` that reaches here is returned as is.
  */
 export function nextBundleKey(bundles, preferredName, seedLocator) {
     return deriveBundleId(preferredName, seedLocator, new Set(Object.keys(bundles)));

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

@@ -3,6 +3,7 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import path from "node:path";
 import { detectAdapterId } from "../../core/adapter/detect-adapter.js";
+import { validateExplicitBundleName } from "../../core/bundle-id.js";
 import { isRemoteUrl } from "../../core/common.js";
 import { bundleEntryToSourceEntry, bundlesToSourceEntries, getSources, mutateConfig } from "../../core/config/config.js";
 import { ConfigError, UsageError } from "../../core/errors.js";
@@ -51,7 +52,10 @@ export function addStash(opts) {
         const bundles = { ...(config.bundles ?? {}) };
         let key;
         if (useDescriptorPath) {
-            if (bundleKeyForUrl(config, target)) {
+            const existingKey = bundleKeyForUrl(config, target);
+            if (name !== undefined)
+                validateExplicitBundleName(bundles, name, existingKey);
+            if (existingKey) {
                 const already = targetIsUrl ? "Source URL already configured" : "Source already configured";
                 result = { sources: getSources(config), added: false, message: already };
                 return config;
@@ -69,7 +73,10 @@ export function addStash(opts) {
         }
         else {
             const resolvedPath = path.resolve(target);
-            if (bundleKeyForPath(config, resolvedPath)) {
+            const existingKey = bundleKeyForPath(config, resolvedPath);
+            if (name !== undefined)
+                validateExplicitBundleName(bundles, name, existingKey);
+            if (existingKey) {
                 result = { sources: getSources(config), added: false, message: "Source path already configured" };
                 return config;
             }

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

@@ -26,7 +26,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { toPosix } from "../common.js";
-import { DERIVED_SUFFIX, SCRIPT_EXTENSIONS, WORKFLOW_EXTENSIONS } from "../recognition-util.js";
+import { SCRIPT_EXTENSIONS, WORKFLOW_EXTENSIONS } from "../recognition-util.js";
 const workflowSpec = {
     isRelevantFile: (fileName) => WORKFLOW_EXTENSIONS.includes(path.extname(fileName).toLowerCase()),
     toCanonicalName: (typeRoot, filePath) => {
@@ -245,21 +245,12 @@ export function assetPathForName(assetType, typeRoot, name) {
  * "default" alias is genuinely dual-owned: both `<dir>/.env` and
  * `<dir>/default.env` derive the same canonical name (`toCanonicalName`
  * above), so a physical-owner lookup must consider both without reading
- * either file. `memory` has a second, analogous duality (#882): a ref to
- * `<name>` may own either `<name>.md` or the LLM-inferred `<name>.derived.md`
- * twin — `.derived` is a provenance marker on the SAME identity, not part of
- * the name (see `resolveParentRef`/`isDerivedMemory` in
- * `commands/improve/memory/derived-ref.ts`, and the belief-edge identity
- * channel's own `memory:<name>.derived` refs). The plain `.md` file wins when
- * both exist, so it stays `primary` — first in the returned list — and every
- * caller here already prefers the first candidate that exists on disk. Every
- * other placement type has exactly one inverse spelling.
+ * either file. Every other placement type has exactly one inverse spelling —
+ * including `memory`: `<name>.derived.md` is a separate item that owns
+ * `<name>.derived`, never a second spelling of `<name>`.
  */
 export function assetPathCandidatesForName(assetType, typeRoot, name) {
     const primary = assetPathForName(assetType, typeRoot, name);
-    if (assetType === "memory" && !name.endsWith(DERIVED_SUFFIX)) {
-        return [primary, assetPathForName(assetType, typeRoot, `${name}${DERIVED_SUFFIX}`)];
-    }
     if (assetType !== "env")
         return [primary];
     const base = name === "default" ? "" : name.endsWith("/default") ? name.slice(0, -"default".length) : undefined;

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

@@ -30545,7 +30545,6 @@ var SCRIPT_EXTENSIONS = new Set([
   ".kts"
 ]);
 var WORKFLOW_EXTENSIONS = [".md", ".yml"];
-var DERIVED_SUFFIX = ".derived";
 var KNOWN_TYPES = [
   "skill",
   "command",
@@ -30703,9 +30702,6 @@ function assetPathForName(assetType, typeRoot, name) {
 }
 function assetPathCandidatesForName(assetType, typeRoot, name) {
   const primary = assetPathForName(assetType, typeRoot, name);
-  if (assetType === "memory" && !name.endsWith(DERIVED_SUFFIX)) {
-    return [primary, assetPathForName(assetType, typeRoot, `${name}${DERIVED_SUFFIX}`)];
-  }
   if (assetType !== "env")
     return [primary];
   const base = name === "default" ? "" : name.endsWith("/default") ? name.slice(0, -"default".length) : undefined;

package/dist/scripts/akm-migrate.js

@@ -29873,7 +29873,6 @@ var SCRIPT_EXTENSIONS = new Set([
   ".kts"
 ]);
 var WORKFLOW_EXTENSIONS = [".md", ".yml"];
-var DERIVED_SUFFIX = ".derived";
 var KNOWN_TYPES = [
   "skill",
   "command",
@@ -30031,9 +30030,6 @@ function assetPathForName(assetType, typeRoot, name) {
 }
 function assetPathCandidatesForName(assetType, typeRoot, name) {
   const primary = assetPathForName(assetType, typeRoot, name);
-  if (assetType === "memory" && !name.endsWith(DERIVED_SUFFIX)) {
-    return [primary, assetPathForName(assetType, typeRoot, `${name}${DERIVED_SUFFIX}`)];
-  }
   if (assetType !== "env")
     return [primary];
   const base = name === "default" ? "" : name.endsWith("/default") ? name.slice(0, -"default".length) : undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.17-alpha.4",
+  "version": "0.9.17-alpha.5",
   "type": "module",
   "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
   "keywords": [