akm-cli 0.9.0-rc.8 → 0.9.0

package/dist/core/asset/resolve-ref.js

@@ -34,7 +34,7 @@
  * grammar to bridge any more.
  */
 import { NotFoundError, UsageError } from "../errors.js";
-import { stashDirFor, typeForStashDir } from "./asset-placement.js";
+import { deriveCanonicalAssetNameFromStashRoot, placementSpecFor, stashDirFor, typeForStashDir, } from "./asset-placement.js";
 import { isBundleSlug, parseBundleRef } from "./asset-ref.js";
 /**
  * Resolve a maybe-short input ref to a fully-qualified {@link ResolvedRef}
@@ -82,10 +82,10 @@ function notFound(conceptId, triedForms, ctx) {
     return new NotFoundError(`No bundle contains concept "${conceptId}"${scope} (tried ${forms}).`, "ASSET_NOT_FOUND");
 }
 /**
- * D-R2 conceptId derivation from a legacy `type`/`name` pair
+ * D-R2 conceptId derivation from an asset `type`/`name` pair
  * (`stashDirFor(type)/name`; bare name for a foreign type with no placement
  * stash-subdir). Kept self-contained so {@link displayRef} — a PERMANENT display
- * rule — does not depend on the transient legacy shims.
+ * rule remains independent of input parsing.
  *
  * Exported (Chunk-8 WI-8.5c) as the ONE conceptId derivation the improve
  * correlation sites (`eligibility.ts` candidate refs, `salience.ts`
@@ -97,6 +97,19 @@ export function conceptIdFromTypeName(type, name) {
     const stashDir = stashDirFor(type);
     return stashDir !== undefined ? `${stashDir}/${name}` : name;
 }
+/**
+ * User-facing conceptId for a file on disk, derived through the placement
+ * spec's canonical-name rule — the ONE way a diagnostic should spell a ref it
+ * expects the user to paste into `akm show`. (The dangerous-env-key lint used
+ * to hand-build `env:<base>` colon refs the parser rejects; both its emission
+ * sites now route through here.) For a type with no placement spec — which no
+ * built-in caller passes — falls back to the raw name so the output is still
+ * informative rather than empty.
+ */
+export function conceptIdForStashFile(type, stashRoot, filePath) {
+    const name = deriveCanonicalAssetNameFromStashRoot(type, stashRoot, filePath);
+    return name === undefined ? filePath : conceptIdFromTypeName(type, name);
+}
 /**
  * Build the USER-FACING / envelope ref string for an indexed item, applying the
  * Chunk-5 flip F4b output-spelling rule (orchestrator decision; ref-grammar
@@ -116,19 +129,23 @@ export function conceptIdFromTypeName(type, name) {
  *     derived slug bundle id, never the retired `origin//type:name` spelling.
  */
 export function displayRef(item, defaultBundleId) {
-    const conceptId = item.conceptId ?? conceptIdFromTypeName(item.type, item.name);
-    const { bundleId } = item;
-    // Default/primary bundle → SHORT conceptId (the flip). `"local"`/`"stash"` are
-    // the primary-stash origin sentinels (never real bundle slugs — they name the
-    // workspace's own stash, exactly where the pre-0.9.0 output was un-qualified),
-    // so they display short too.
-    if (bundleId === undefined || bundleId === defaultBundleId || bundleId === "local" || bundleId === "stash")
+    return displayRefForConceptId(item.conceptId ?? conceptIdFromTypeName(item.type, item.name), item.bundleId, defaultBundleId);
+}
+/**
+ * The F4b output-spelling flip itself, for a caller that already holds the
+ * conceptId (no `type`/`name` derivation needed — e.g. lint findings built
+ * from {@link conceptIdForStashFile}). {@link displayRef} delegates here, so
+ * the short-default / qualified-secondary rule still has exactly one home.
+ */
+export function displayRefForConceptId(conceptId, bundleId, defaultBundleId) {
+    // Default/primary bundle → SHORT conceptId (the flip).
+    if (bundleId === undefined || bundleId === defaultBundleId)
         return conceptId;
     // Non-default bundle → the new fully-qualified `bundle//conceptId` grammar.
     return `${bundleId}//${conceptId}`;
 }
 /**
- * Split a qualified conceptId (`<stash-subdir>/<name>`) back to its legacy
+ * Split a qualified conceptId (`<stash-subdir>/<name>`) into its asset
  * `type`/`name`, or `undefined` when the leading segment is not a known stash
  * subdir (a bare-name conceptId from a foreign type — no legacy predicate
  * applies). The PERMANENT D-R2 reverse table: the input boundary uses it to map
@@ -144,6 +161,54 @@ export function typeNameFromConceptId(conceptId) {
         return undefined;
     return { type, name: conceptId.slice(slash + 1) };
 }
+/**
+ * D11 — the opaque-adapter-conceptId fallback. `typeNameFromConceptId` only
+ * ever answers for the PLACEMENT_SPECS stash-resident subset (D-R2); a
+ * conceptId whose leading segment is NOT a registered placement stashDir is
+ * still perfectly legal DATA per D11 — an OKF item (`tables/customers`), a
+ * website page, a wiki pageKind, an adapter `instruction` doc, … — and the
+ * ref-consuming commands must accept it rather than treat "not an AKM
+ * placement dir" as "malformed ref". This function draws the line: it accepts
+ * any well-formed `<segment>/<rest>` conceptId (so the shape is still
+ * anchored — a bare no-slash name stays the caller's job to pre-qualify with a
+ * default type, the existing env/secret/`akm mv` "bare name" convenience), and
+ * REJECTS anything shaped like the retired `type:name` colon grammar (Q-02):
+ * a `:` in the leading segment is that grammar smuggled through a conceptId
+ * string (e.g. `script:db/migrate/run.sh`, `workflow:release/train`), not a
+ * real adapter directory name, so it is refused rather than silently
+ * reinterpreted as opaque data.
+ *
+ * `name` deliberately carries the FULL original conceptId, not just the tail.
+ * This is what makes the pair round-trip through the UNCHANGED
+ * {@link conceptIdFromTypeName} (`stashDirFor(type)/name`, bare `name` when
+ * `type` has no placement stashDir): since an opaque `type` never owns a
+ * placement stashDir, `conceptIdFromTypeName(type, name)` falls to its bare-
+ * `name` branch and returns `name` verbatim — the original conceptId,
+ * unchanged — instead of losing the leading segment. `type` itself carries
+ * the leading segment (informational/behavioral use: `.type === "lesson"`
+ * checks correctly miss for opaque data) UNLESS that segment happens to
+ * collide with a real PLACEMENT_SPECS type key that merely uses a different
+ * stashDir spelling (e.g. a foreign top-level dir literally named "skill",
+ * singular) — that pathological case would make `stashDirFor` succeed on the
+ * "type" and corrupt the round-trip, so it falls back to the full conceptId as
+ * `type` too (never a placement key, since a placement key never contains
+ * `/`).
+ *
+ * This intentionally does NOT collapse the KNOWN_TYPES/PLACEMENT_SPECS split:
+ * `typeNameFromConceptId` (PLACEMENT_SPECS only) is untouched, and an opaque
+ * `type` returned here is never a {@link KnownType} — it is a passthrough
+ * label, not a claim that AKM recognizes or owns the concept.
+ */
+function opaqueRefParts(conceptId, allowRoot = false) {
+    const slash = conceptId.indexOf("/");
+    if (slash <= 0)
+        return allowRoot && !conceptId.includes(":") ? { type: conceptId, name: conceptId } : undefined;
+    const segment = conceptId.slice(0, slash);
+    if (segment.includes(":"))
+        return undefined; // retired `type:name` grammar, not opaque data (Q-02).
+    const type = placementSpecFor(segment) === undefined ? segment : conceptId;
+    return { type, name: conceptId };
+}
 /**
  * Parse a RAW user / CLI / API ref string in the 0.9.0 `[bundle//]conceptId`
  * grammar, returning it in today's {@link AssetRef} value-object shape
@@ -154,9 +219,14 @@ export function typeNameFromConceptId(conceptId) {
  *
  * Mapping (new grammar → {@link AssetRef}):
  *   - `conceptId` → `type`/`name` via {@link typeNameFromConceptId} (the D-R2
- *     static stash-subdir table). A conceptId whose leading segment is not a
- *     known stash subdir has no legacy `type` predicate — the same outcome an
- *     unknown asset type produces today (a not-found).
+ *     static stash-subdir table) when the leading segment is a known AKM
+ *     placement stashDir, else via {@link opaqueRefParts} (D11 — the ref-parser
+ *     seam accepts opaque adapter conceptIds, e.g. OKF items, website pages,
+ *     wiki pageKinds, adapter `instruction` docs) when it is merely a well-
+ *     formed but foreign `<segment>/<rest>` shape. A conceptId that is neither
+ *     — no slash at all, or a retired colon-grammar shape smuggled through —
+ *     has no type predicate: the same not-found outcome a genuine typo
+ *     produces today.
  *   - `bundle`    → `origin`. A new-grammar bundle slug is a registryId-shaped
  *     id by construction, so it flows straight into the legacy origin channel
  *     that `resolveSourcesForOrigin` matches on `registryId`. The SHORT form (no
@@ -168,11 +238,11 @@ export function parseRefInput(raw) {
     if (ref.fragment !== undefined) {
         throw new UsageError(`Export fragment "#${ref.fragment}" is not accepted here — drop it from "${raw.trim()}".`, "INVALID_FLAG_VALUE");
     }
-    const legacy = typeNameFromConceptId(ref.conceptId);
-    if (legacy === undefined) {
+    const parts = typeNameFromConceptId(ref.conceptId) ?? opaqueRefParts(ref.conceptId, ref.bundle !== undefined);
+    if (parts === undefined) {
         throw new NotFoundError(`Unrecognized asset ref "${raw.trim()}": conceptId "${ref.conceptId}" has no known asset-type prefix.`, "ASSET_NOT_FOUND");
     }
-    return { type: legacy.type, name: legacy.name, origin: ref.bundle };
+    return { type: parts.type, name: parts.name, origin: ref.bundle };
 }
 /**
  * Parse a CLI/API ref that MAY be qualified by a NON-slug origin — a registry
@@ -215,7 +285,8 @@ export function isFullRefInput(raw) {
     if (!trimmed)
         return false;
     try {
-        return typeNameFromConceptId(parseBundleRef(trimmed).conceptId) !== undefined;
+        const parsed = parseBundleRef(trimmed);
+        return parsed.bundle !== undefined || typeNameFromConceptId(parsed.conceptId) !== undefined;
     }
     catch {
         return false;

package/dist/core/asset/stash-meta.js

@@ -7,7 +7,7 @@
  * A stash may carry an optional, human-authored `.meta/` directory at its
  * root holding orientation docs for the stash as a whole: purpose, key
  * assets, conventions, maintainer info. Because `.meta/` is a dot-directory,
- * the indexer's walker already skips it (see `src/indexer/walker.ts`), so
+ * the indexer's walker already skips it (see `src/indexer/walk/walker.ts`), so
  * these files never pollute the search corpus. They are surfaced on demand
  * via `akm show [<origin>//]meta[:<name>]`, which direct-reads the file
  * rather than going through the index.

package/dist/core/bundle-id.js

@@ -0,0 +1,51 @@
+// 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 crypto from "node:crypto";
+import path from "node:path";
+import { isBundleSlug } from "./asset/asset-ref.js";
+/** Deterministic, filesystem-safe bundle slug from a source path. */
+export function slugForPath(sourcePath) {
+    const resolved = path.resolve(sourcePath);
+    const base = path
+        .basename(resolved)
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    if (base.length > 0)
+        return base;
+    return `bundle-${shortHash(resolved)}`;
+}
+/** Derive one batch-unique bundle id. */
+export function deriveBundleId(registryId, sourcePath, usedIds) {
+    const preferred = registryId && registryId.length > 0 && isBundleSlug(registryId) ? registryId : slugForPath(sourcePath);
+    const id = ensureUniqueId(preferred, sourcePath, usedIds);
+    usedIds.add(id);
+    return id;
+}
+/** Derive an ordered batch while reserving every explicit configured bundle id. */
+export function deriveBundleIds(sources) {
+    const usedIds = new Set();
+    const reservedIds = new Set(sources.flatMap((source) => (source.registryId && isBundleSlug(source.registryId) ? [source.registryId] : [])));
+    return sources.map((source) => {
+        const id = source.registryId && isBundleSlug(source.registryId)
+            ? deriveBundleId(source.registryId, source.path, usedIds)
+            : deriveBundleId(undefined, source.path, new Set([...usedIds, ...reservedIds]));
+        usedIds.add(id);
+        return id;
+    });
+}
+function ensureUniqueId(preferred, sourcePath, used) {
+    if (!used.has(preferred))
+        return preferred;
+    const suffixed = `${preferred}-${shortHash(path.resolve(sourcePath))}`;
+    if (!used.has(suffixed))
+        return suffixed;
+    let n = 2;
+    while (used.has(`${suffixed}-${n}`))
+        n++;
+    return `${suffixed}-${n}`;
+}
+function shortHash(input) {
+    return crypto.createHash("sha256").update(input).digest("hex").slice(0, 8);
+}

package/dist/core/common.js

@@ -80,60 +80,105 @@ export function readTextFileWithLimit(filePath, maxBytes, label = "File") {
  *   2. fsync the parent directory after rename, so the directory entry change
  *      is durable too. Some filesystems (FAT, certain FUSE mounts) don't
  *      support directory fsync; we ignore EINVAL/ENOTSUP so atomic writes
- *      don't fail on exotic mounts.
+ *      don't fail on those mounts. Windows does not support opening a
+ *      directory for fsync, so the directory-sync step is skipped there.
  */
 export function writeFileAtomic(target, content, mode) {
     const tmp = `${target}.tmp.${process.pid}.${crypto.randomBytes(8).toString("hex")}`;
-    const fd = fs.openSync(tmp, "w", mode ?? 0o600);
+    const data = typeof content === "string" ? Buffer.from(content) : content;
+    const fileMode = mode ?? 0o600;
+    let fd;
+    let tempOwned = false;
+    let renamed = false;
+    let failed = false;
+    let failure;
     try {
-        fs.writeSync(fd, typeof content === "string" ? Buffer.from(content) : content);
-        try {
-            fs.fdatasyncSync(fd);
-        }
-        catch {
-            // Best-effort: some pseudo-filesystems lack fdatasync. Fall through
-            // to closeSync — the rename below still preserves atomicity even if
-            // the data isn't durable, and the calling code's retry will recover.
+        fd = fs.openSync(tmp, "wx", fileMode);
+        tempOwned = true;
+        if (process.platform !== "win32")
+            fs.fchmodSync(fd, fileMode);
+        let offset = 0;
+        while (offset < data.byteLength) {
+            const written = fs.writeSync(fd, data, offset, data.byteLength - offset);
+            if (written <= 0)
+                throw new Error(`Could not make progress writing atomic temp file ${tmp}.`);
+            offset += written;
         }
+        fs.fdatasyncSync(fd);
+        fs.closeSync(fd);
+        fd = undefined;
+        fs.renameSync(tmp, target);
+        renamed = true;
+    }
+    catch (error) {
+        failed = true;
+        failure = error;
     }
     finally {
-        fs.closeSync(fd);
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch (error) {
+                if (!failed) {
+                    failed = true;
+                    failure = error;
+                }
+            }
+        }
+        if (tempOwned && !renamed) {
+            try {
+                fs.unlinkSync(tmp);
+            }
+            catch (error) {
+                if (!failed && !hasErrnoCode(error, "ENOENT")) {
+                    failed = true;
+                    failure = error;
+                }
+            }
+        }
     }
-    fs.renameSync(tmp, target);
-    try {
-        const dirFd = fs.openSync(path.dirname(target), "r");
+    if (failed)
+        throw failure;
+    if (process.platform !== "win32") {
+        let dirFd;
         try {
-            fs.fsyncSync(dirFd);
+            dirFd = fs.openSync(path.dirname(target), "r");
+        }
+        catch (error) {
+            if (hasErrnoCode(error, "EINVAL") || hasErrnoCode(error, "ENOTSUP"))
+                return;
+            throw error;
+        }
+        try {
+            try {
+                fs.fsyncSync(dirFd);
+            }
+            catch (error) {
+                if (!hasErrnoCode(error, "EINVAL") && !hasErrnoCode(error, "ENOTSUP"))
+                    throw error;
+            }
         }
         finally {
             fs.closeSync(dirFd);
         }
     }
-    catch {
-        // Directory fsync is unsupported on FAT, some FUSE mounts, and Windows
-        // (where directories cannot be opened for read like POSIX). Silently
-        // ignore so writeFileAtomic remains portable.
-    }
 }
 /**
  * Resolve the stash directory using a three-level fallback chain:
- *   1. AKM_STASH_DIR environment variable (override for CI/scripts)
- *   2. stashDir field in config.json
+ *   1. AKM_BUNDLE_DIR environment variable (override for CI/scripts)
+ *   2. The configured default bundle path
  *   3. Platform default (~/akm or ~/Documents/akm on Windows)
  *
- * Pure read: never writes to disk. The legacy `readOnly` option is accepted
- * (and ignored) for one release cycle so older callers continue to compile;
- * it can be removed in the next minor bump.
- *
  * Throws if no valid stash directory is found.
  */
-export function resolveStashDir(_options, env = process.env) {
+export function resolveStashDir(env = process.env) {
     // 1. Env var override (for CI, scripts, testing)
-    const envDir = env.AKM_STASH_DIR?.trim();
+    const envDir = env.AKM_BUNDLE_DIR?.trim();
     if (envDir) {
         return validateStashDir(envDir);
     }
-    // 2. Config file stashDir field
+    // 2. Configured default bundle path
     const configStashDir = readStashDirFromConfig();
     if (configStashDir)
         return validateStashDir(configStashDir);
@@ -142,7 +187,7 @@ export function resolveStashDir(_options, env = process.env) {
     if (isValidDirectory(defaultDir)) {
         return defaultDir;
     }
-    throw new ConfigError(`No stash directory found. Run "akm init" to create one at ${defaultDir}.`, "STASH_DIR_NOT_FOUND");
+    throw new ConfigError(`No bundle directory found. Run "akm bundle create" to create one at ${defaultDir}.`, "STASH_DIR_NOT_FOUND");
 }
 function validateStashDir(raw) {
     const stashDir = path.resolve(raw);
@@ -151,10 +196,10 @@ function validateStashDir(raw) {
         stat = fs.statSync(stashDir);
     }
     catch {
-        throw new ConfigError(`Unable to read stash directory at "${stashDir}".`, "STASH_DIR_UNREADABLE");
+        throw new ConfigError(`Unable to read bundle directory at "${stashDir}".`, "STASH_DIR_UNREADABLE");
     }
     if (!stat.isDirectory()) {
-        throw new ConfigError(`Stash path must point to a directory: "${stashDir}".`, "STASH_DIR_NOT_A_DIRECTORY");
+        throw new ConfigError(`Bundle path must point to a directory: "${stashDir}".`, "STASH_DIR_NOT_A_DIRECTORY");
     }
     return stashDir;
 }
@@ -172,7 +217,7 @@ function isValidDirectory(dir) {
  *
  * Reads ONLY the 0.9.0 `bundles`/`defaultBundle` shape. A config still carrying
  * the retired `stashDir`/`sources`/`installed` keys (with no usable bundles
- * path) is an unmigrated config: this refuses it with the same `akm migrate
+ * path) is an unmigrated config: this refuses it with the same `akm-migrate
  * apply` hint the schema hard-reject uses (config-schema.ts), rather than
  * silently honouring the retired key — so every `resolveStashDir` caller gets
  * the coherent migrate posture instead of split-brain success.
@@ -197,14 +242,37 @@ function readStashDirFromConfig() {
             typeof bundles[defaultBundle] === "object" &&
             typeof bundles[defaultBundle].path === "string" &&
             bundles[defaultBundle].path.trim()) {
-            return bundles[defaultBundle].path.trim();
+            const bundle = bundles[defaultBundle];
+            const bundlePath = bundle.path.trim();
+            if (bundle.components !== undefined) {
+                if (typeof bundle.components !== "object" || bundle.components === null) {
+                    throw new ConfigError("A bundle components map must contain exactly one component.", "INVALID_CONFIG_FILE");
+                }
+                const components = Object.values(bundle.components);
+                if (components.length !== 1) {
+                    throw new ConfigError("A bundle components map must contain exactly one component.", "INVALID_CONFIG_FILE");
+                }
+                const component = components[0];
+                if (typeof component === "object" && component !== null) {
+                    const componentConfig = component;
+                    if (typeof componentConfig.root !== "string")
+                        return bundlePath;
+                    const bundleRoot = path.resolve(bundlePath);
+                    const componentRoot = path.resolve(bundleRoot, componentConfig.root);
+                    if (!isWithin(componentRoot, bundleRoot)) {
+                        throw new ConfigError(`Component root "${componentConfig.root}" escapes bundle "${defaultBundle}".`, "INVALID_CONFIG_FILE");
+                    }
+                    return componentRoot;
+                }
+            }
+            return bundlePath;
         }
         // Retired pre-cutover shape with no usable bundles path: refuse with the
         // migrate hint (matches the schema's hard-reject, config-schema.ts) instead
         // of silently resolving the old key.
         for (const key of ["stashDir", "sources", "installed"]) {
             if (key in raw && raw[key] !== undefined) {
-                throw new ConfigError(`${key} is the retired pre-cutover source shape; run \`akm migrate apply\` to convert it to bundles`, "INVALID_CONFIG_FILE");
+                throw new ConfigError(`${key} is the retired pre-cutover source shape; run \`akm-migrate apply\` to convert it to bundles`, "INVALID_CONFIG_FILE");
             }
         }
     }
@@ -308,6 +376,8 @@ export async function fetchWithTimeout(url, opts, timeoutMs = 30_000, signal) {
         }
     }
     try {
+        if (controller.signal.aborted)
+            throw controller.signal.reason ?? new Error(`Request aborted: ${url}`);
         return await fetch(url, { ...opts, signal: controller.signal });
     }
     catch (err) {
@@ -337,11 +407,12 @@ export async function fetchWithRetry(url, init, options) {
     const timeout = options?.timeout ?? 30_000;
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
         try {
-            const response = await fetchWithTimeout(url, init, timeout);
+            const response = await fetchWithTimeout(url, init, timeout, init?.signal ?? undefined);
             if (attempt < maxRetries && shouldRetry(response.status)) {
                 const retryAfter = parseRetryAfter(response);
                 const delay = retryAfter ?? baseDelay * 2 ** attempt * (0.5 + Math.random() * 0.5);
-                await new Promise((r) => setTimeout(r, delay));
+                await response.body?.cancel().catch(() => undefined);
+                await abortableDelay(delay, init?.signal);
                 continue;
             }
             return response;
@@ -349,12 +420,41 @@ export async function fetchWithRetry(url, init, options) {
         catch (err) {
             if (attempt >= maxRetries)
                 throw err;
+            // A caller-supplied abort is terminal: never keep retrying past it.
+            if (init?.signal?.aborted)
+                throw err;
             const delay = baseDelay * 2 ** attempt * (0.5 + Math.random() * 0.5);
-            await new Promise((r) => setTimeout(r, delay));
+            await abortableDelay(delay, init?.signal);
         }
     }
     throw new Error("fetchWithRetry: unreachable");
 }
+/**
+ * Sleep, but wake immediately if `signal` aborts.
+ *
+ * A server-supplied `Retry-After` is honored verbatim and can be arbitrarily
+ * large. Sleeping it out with a bare `setTimeout` ignored the caller's abort
+ * signal entirely, so a single `429` could park an operation far past any
+ * deadline its caller believed it had imposed — the request timeout bounds
+ * only the request, never the wait between attempts.
+ */
+function abortableDelay(ms, signal) {
+    if (!signal)
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    if (signal.aborted)
+        return Promise.reject(signal.reason ?? new Error("Aborted"));
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason ?? new Error("Aborted"));
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
 function shouldRetry(status) {
     return status === 429 || status >= 500;
 }
@@ -560,6 +660,20 @@ export function toErrorMessage(error) {
 export function todayIso() {
     return new Date().toISOString().slice(0, 10);
 }
+/**
+ * `YYYY-MM-DD` in LOCAL time — deliberately not {@link todayIso}, which is
+ * UTC and can differ near midnight. This is the spelling the `updated:`
+ * frontmatter stampers share (`core/asset/akm-markdown.ts` on write,
+ * `commands/lint/base-linter.ts` on `--fix`), so the field's format has one
+ * definition even though the two stampers pick different instants (now vs
+ * file mtime).
+ */
+export function localDateStamp(d) {
+    const y = d.getFullYear();
+    const m = String(d.getMonth() + 1).padStart(2, "0");
+    const day = String(d.getDate()).padStart(2, "0");
+    return `${y}-${m}-${day}`;
+}
 /**
  * Return a filesystem-safe timestamp string derived from the current instant.
  * Colons and dots are replaced with hyphens so the result is safe as a

package/dist/core/config/config-io.js

@@ -156,7 +156,18 @@ function pruneOldBackups(backupDir) {
 export function getConfigLockPath() {
     return path.join(getConfigDir(), "config.json.lck");
 }
-const CONFIG_LOCK_MAX_RETRIES = 10;
+// Total wait budget for a CONTENDED lock: retries × delay. An abandoned lock
+// is not covered by this budget — it is reclaimed by the stale-lock probe
+// below — so this only bounds how long a caller queues behind live writers.
+//
+// 10 × 50ms (500ms) was too thin: N concurrent `akm config set` processes
+// serialize on this lock, so the last one in line waits for all N-1 holders.
+// On a loaded machine (CI runs four test shards in parallel) eight contenders
+// exhausted the budget and one exited with "Timed out waiting for config
+// lock", which is a spurious failure — the lock was healthy and simply busy.
+// 2s gives real concurrent use headroom while still failing promptly against a
+// genuinely wedged (but non-stale) holder.
+const CONFIG_LOCK_MAX_RETRIES = 40;
 const CONFIG_LOCK_RETRY_DELAY_MS = 50;
 /**
  * Block the current thread for `ms` without busy-spinning (H8). Delegates to

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

@@ -46,6 +46,7 @@ import { z } from "zod";
 import { BUILTIN_IMPROVE_STRATEGY_NAMES, IMPROVE_PROCESS_ENGINE_CAPABILITIES } from "./engine-semantics.js";
 import { EmbeddingConnectionConfigSchema } from "./schema/embedding.js";
 import { EnginesSchema } from "./schema/engines.js";
+import { ExperimentalConfigSchema } from "./schema/experimental.js";
 import { FeedbackConfigSchema } from "./schema/feedback.js";
 import { ImproveConfigSchema } from "./schema/improve.js";
 import { IndexConfigSchema } from "./schema/index-config.js";
@@ -58,6 +59,7 @@ import { WorkflowConfigSchema } from "./schema/workflow.js";
 // ── Section re-exports (keep every `./config-schema` import path working) ────
 export { EmbeddingConnectionConfigSchema } from "./schema/embedding.js";
 export { EngineConfigSchema, EnginesSchema, LlmConnectionConfigSchema, LlmProfileConfigSchema } from "./schema/engines.js";
+export { ExperimentalConfigSchema } from "./schema/experimental.js";
 export { FEEDBACK_FAILURE_MODES, FeedbackConfigSchema } from "./schema/feedback.js";
 export { ImproveConfigSchema } from "./schema/improve.js";
 export { ConsolidateProcessConfigSchema, DistillProcessConfigSchema, ExtractProcessConfigSchema, GraphExtractionProcessConfigSchema, ImproveProcessConfigSchema, ImproveProfileConfigSchema, MemoryInferenceProcessConfigSchema, ProactiveMaintenanceProcessConfigSchema, ReflectProcessConfigSchema, TriageProcessConfigSchema, ValidationProcessConfigSchema, } from "./schema/improve-processes.js";
@@ -65,8 +67,8 @@ export { IndexConfigSchema, IndexPassConfigSchema } from "./schema/index-config.
 export { OutputConfigSchema } from "./schema/output.js";
 export { CURRENT_CONFIG_VERSION, LlmInvocationOverridesSchema } from "./schema/primitives.js";
 export { SearchConfigSchema } from "./schema/search.js";
-export { SetupConfigSchema, SetupTaskSchedulesSchema } from "./schema/setup.js";
-export { BundleConfigEntrySchema, BundlesConfigSchema, InstalledStashEntrySchema, RegistryConfigEntrySchema, SourceConfigEntrySchema, } from "./schema/sources-bundles.js";
+export { SetupConfigSchema } from "./schema/setup.js";
+export { BundleConfigEntrySchema, BundlesConfigSchema, RegistryConfigEntrySchema, SourceConfigEntrySchema, } from "./schema/sources-bundles.js";
 export { WorkflowConfigSchema } from "./schema/workflow.js";
 // ── Defaults ───────────────────────────────────────────────────────────────
 export const DefaultsSchema = z
@@ -100,7 +102,7 @@ export const AkmConfigShape = {
     // custom profile's name for the default builder) — unknown keys are inert.
     // Precedence: profile modelAliases > this table > built-in aliases.
     modelAliases: GlobalModelAliasesSchema.optional(),
-    semanticSearchMode: z.enum(["off", "auto"]).default("auto"),
+    semanticSearchMode: z.enum(["off", "auto"]).default("off"),
     embedding: EmbeddingConnectionConfigSchema.optional(),
     index: IndexConfigSchema.optional(),
     registries: z.array(RegistryConfigEntrySchema).optional(),
@@ -109,13 +111,10 @@ export const AkmConfigShape = {
     // trio is hard-rejected at load (see the top-level superRefine). The migrator
     // ({@link migrateConfigSourcesToBundles}) converts a pre-cutover config to this
     // shape before validation. `defaultBundle` names the primary bundle (spec
-    // §11.1 short-ref resolution / D-R4). `SourceConfigEntrySchema` /
-    // `InstalledStashEntrySchema` remain EXPORTED (the migrator + transitional
-    // readers consume them) but are no longer top-level config fields.
+    // §11.1 short-ref resolution / D-R4).
     bundles: BundlesConfigSchema.optional(),
     defaultBundle: nonEmptyString.optional(),
     output: OutputConfigSchema.optional(),
-    writable: z.boolean().optional(),
     defaultWriteTarget: nonEmptyString.optional(),
     search: SearchConfigSchema.optional(),
     feedback: FeedbackConfigSchema.optional(),
@@ -123,8 +122,20 @@ export const AkmConfigShape = {
     improve: ImproveConfigSchema.optional(),
     workflow: WorkflowConfigSchema.optional(),
     setup: SetupConfigSchema.optional(),
+    // D8 — explicit opt-ins for behaviour outside the stability contract. Every
+    // key defaults to OFF; see `src/core/config/experimental.ts` for the readers.
+    experimental: ExperimentalConfigSchema.optional(),
 };
 export const AkmConfigBaseSchema = z.object(AkmConfigShape).passthrough();
+/**
+ * Per-key overrides for the retired `stashDir`/`sources`/`installed` source-
+ * shape rejection below. Keys without an entry fall back to the shared
+ * "retired pre-cutover source shape" message, which already names the
+ * replacement (bundles) and the migration command.
+ */
+const RETIRED_SOURCE_SHAPE_KEY_MESSAGES = {
+    stashDir: "stashDir is retired in 0.9; the stash path now comes from `bundles`. Run `akm-migrate apply` to convert a pre-0.9 config, or see `akm config path --all` / `akm info`.",
+};
 export const AkmConfigSchema = AkmConfigBaseSchema.superRefine((config, ctx) => {
     const raw = config;
     for (const key of ["profiles", "llm", "agent", "features", "stashes"]) {
@@ -157,10 +168,18 @@ export const AkmConfigSchema = AkmConfigBaseSchema.superRefine((config, ctx) =>
             ctx.addIssue({
                 code: z.ZodIssueCode.custom,
                 path: [key],
-                message: `${key} is the retired pre-cutover source shape; run \`akm migrate apply\` to convert it to bundles`,
+                message: RETIRED_SOURCE_SHAPE_KEY_MESSAGES[key] ??
+                    `${key} is the retired pre-cutover source shape; run \`akm-migrate apply\` to convert it to bundles`,
             });
         }
     }
+    if ("writable" in raw) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["writable"],
+            message: "top-level writable is not supported; configure bundles.<id>.writable instead",
+        });
+    }
     // `defaultBundle`, when present, must name a configured bundle.
     if (config.defaultBundle !== undefined) {
         if (config.bundles === undefined) {
@@ -215,6 +234,14 @@ export const AkmConfigSchema = AkmConfigBaseSchema.superRefine((config, ctx) =>
             message: "llmEngine must name an LLM engine",
         });
     }
+    const workflowJudge = config.workflow?.judgeEngine;
+    if (workflowJudge && !config.engines?.[workflowJudge]) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["workflow", "judgeEngine"],
+            message: "judgeEngine does not name a configured engine",
+        });
+    }
     const defaultStrategy = config.defaults?.improveStrategy;
     if (defaultStrategy &&
         !BUILTIN_IMPROVE_STRATEGY_NAMES.includes(defaultStrategy) &&