akm-cli 0.9.6 → 0.9.8-beta.1

package/dist/core/adapter/adapters/generic-files-adapter.js

@@ -23,19 +23,13 @@
  */
 import path from "node:path";
 import { parseFrontmatter } from "../../asset/frontmatter.js";
+import { toPosix } from "../../common.js";
 import { SCRIPT_EXTENSIONS } from "../../recognition-util.js";
-import { hashContent, nonEmptyString, readTags, runBaseValidateChecks } from "./shared.js";
+import { hashContent, nonEmptyString, RESERVED_FILES, readTags, runBaseValidateChecks } from "./shared.js";
 /** A generic-files bundle is single-component; its one component is `main`. */
 const COMPONENT_ID = "main";
 /** Markdown / plain-text extensions classified as `document`. */
 const DOCUMENT_EXTENSIONS = new Set([".md", ".markdown", ".txt", ".text"]);
-/** OKF reserved structural files (D-R6) — excluded from the catch-all, case-insensitive. */
-const RESERVED_FILES = new Set(["index.md", "log.md"]);
-/** Upper bound on the bounded `content` FTS field (mirrors okf-adapter). */
-const MAX_CONTENT_CHARS = 100_000;
-function toPosix(p) {
-    return p.replace(/\\/g, "/");
-}
 function isReserved(base) {
     return RESERVED_FILES.has(base.toLowerCase());
 }
@@ -69,7 +63,7 @@ function recognize(c, file) {
         adapterId: "generic-files",
         type,
         name,
-        content: body.length > MAX_CONTENT_CHARS ? body.slice(0, MAX_CONTENT_CHARS) : body,
+        content: body,
     };
     if (type !== "script")
         doc.ownsPresentation = true;

package/dist/core/adapter/adapters/llm-wiki-adapter.js

@@ -73,6 +73,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { parseFrontmatter, parseFrontmatterBlock } from "../../asset/frontmatter.js";
+import { toPosix } from "../../common.js";
 import { hashContent, nonEmptyString } from "./shared.js";
 /** A wiki is a single-component bundle; its one component is conventionally `main` (recognition golden). */
 const WIKI_COMPONENT_ID = "main";
@@ -86,12 +87,7 @@ const RESERVED_ROOT_FILES = new Set(["schema.md", "index.md", "log.md"]);
 const RAW_SUBDIR = "raw";
 /** Content subdirectory holding agent-authored pages. */
 const PAGES_SUBDIR = "pages";
-/** Upper bound on the bounded `content` FTS field (mirrors okf-adapter). */
-const MAX_CONTENT_CHARS = 100_000;
 /** POSIX-normalize separators. */
-function toPosix(p) {
-    return p.replace(/\\/g, "/");
-}
 /** conceptId = component-root-relative path minus `.md`. */
 function conceptIdOf(relPath) {
     return toPosix(relPath).replace(/\.md$/i, "");
@@ -280,7 +276,7 @@ function recognize(c, file) {
         ownsPresentation: true,
         type: isRaw ? WIKI_SOURCE_TYPE : (fm.pageKind ?? DEFAULT_PAGE_KIND),
         name: lastSegment,
-        content: body.length > MAX_CONTENT_CHARS ? body.slice(0, MAX_CONTENT_CHARS) : body,
+        content: body,
     };
     if (fm.description !== undefined)
         doc.description = fm.description;

package/dist/core/adapter/adapters/okf-adapter.js

@@ -31,7 +31,8 @@
 import fs from "node:fs";
 import path from "node:path";
 import { parseFrontmatter } from "../../asset/frontmatter.js";
-import { hashContent, nonEmptyString, readTags, runBaseValidateChecks } from "./shared.js";
+import { isRecord, toPosix } from "../../common.js";
+import { hashContent, nonEmptyString, RESERVED_FILES, readTags, runBaseValidateChecks } from "./shared.js";
 /** v0.2 frontmatter keys consumed into first-class fields below (§0.1) — excluded from the generic `documentJson` extras fold alongside the v0.1 five, so nothing is duplicated between a first-class field and the opaque extras bag. */
 const CONSUMED_FRONTMATTER_KEYS = [
     "type",
@@ -46,17 +47,13 @@ const CONSUMED_FRONTMATTER_KEYS = [
     "stale_after",
     "okf_version",
 ];
-/** True for a plain (non-null, non-array) object — the shape every v0.2 mapping (`generated`, one `verified`/`sources` entry) must have. */
-function isPlainObject(value) {
-    return value !== null && typeof value === "object" && !Array.isArray(value);
-}
 /**
  * Parse one `verified:` actor mapping (`{by, at?}`). Tolerant: a missing/blank
  * `by` yields `undefined` (the entry is dropped, never rejecting the document
  * — OKF conformance leniency); `at` is independently optional.
  */
 function parseActorMapping(value) {
-    if (!isPlainObject(value))
+    if (!isRecord(value))
         return undefined;
     const by = nonEmptyString(value.by);
     if (by === undefined)
@@ -96,7 +93,7 @@ function parseOkfSources(value) {
         return undefined;
     const out = [];
     for (const item of value) {
-        if (!isPlainObject(item))
+        if (!isRecord(item))
             continue;
         const resource = nonEmptyString(item.resource);
         if (resource === undefined)
@@ -125,15 +122,7 @@ function parseOkfSources(value) {
 function parseLifecycleStatus(value) {
     return value === "draft" || value === "stable" || value === "deprecated" ? value : undefined;
 }
-/** Reserved OKF files (case-insensitive) — recognized, never indexed as concepts (§5, OKF §1.4). */
-const RESERVED_FILES = new Set(["index.md", "log.md"]);
-/** Upper bound on the bounded `content` FTS field (§3: "content: FTS 1 (bounded)"). Small fixtures are never truncated. */
-const MAX_CONTENT_CHARS = 100_000;
-/** POSIX-normalize separators without importing a cycle-participant helper. */
-function toPosix(p) {
-    return p.replace(/\\/g, "/");
-}
-/** True when `name` (a bare file name) is a reserved OKF file, case-insensitively. */
+/** True when `name` (a bare file name) is a reserved OKF file, case-insensitively (§5, OKF §1.4). */
 function isReservedFileName(name) {
     return RESERVED_FILES.has(name.toLowerCase());
 }
@@ -237,7 +226,7 @@ function recognize(c, file) {
     // `generated.at` — v0.2's replacement for `timestamp` — takes precedence;
     // `timestamp` remains a fully valid fallback (the v0.2-permitted legacy
     // reading, not merely tolerated). Both stay fully optional (never rejects).
-    const generatedMapping = isPlainObject(data.generated) ? data.generated : undefined;
+    const generatedMapping = isRecord(data.generated) ? data.generated : undefined;
     const generatedAt = generatedMapping ? nonEmptyString(generatedMapping.at) : undefined;
     const generatedBy = generatedMapping ? nonEmptyString(generatedMapping.by) : undefined;
     const legacyTimestamp = nonEmptyString(data.timestamp);
@@ -272,7 +261,7 @@ function recognize(c, file) {
         ownsPresentation: true,
         type,
         name,
-        content: body.length > MAX_CONTENT_CHARS ? body.slice(0, MAX_CONTENT_CHARS) : body,
+        content: body,
     };
     if (description !== undefined)
         doc.description = description;

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

@@ -69,6 +69,8 @@ export function readTags(value) {
     const tags = value.filter((tag) => typeof tag === "string" && tag.trim().length > 0);
     return tags.length > 0 ? tags : undefined;
 }
+/** Reserved files (case-insensitive) every concrete adapter recognizes but never indexes as a concept. */
+export const RESERVED_FILES = new Set(["index.md", "log.md"]);
 // ── Base validate checks (port of `BaseLinter.runBaseChecks`) ────────────────
 function checkMissingUpdated(data, frontmatterText) {
     return frontmatterText !== null && !("updated" in data);

package/dist/core/adapter/adapters/tool-dir-shared.js

@@ -49,21 +49,15 @@
 import path from "node:path";
 import { createAdapterExtensions, } from "../../../execution/source.js";
 import { parseFrontmatter } from "../../asset/frontmatter.js";
+import { toPosix } from "../../common.js";
 import { executionDefaultsFromFrontmatter, renderMarkdownExecutionSource } from "../execution-source.js";
 import { skillDirectoryDiagnostics } from "./akm-lint.js";
-import { hashContent, nonEmptyString, readTags, runBaseValidateChecks } from "./shared.js";
-/** OKF reserved structural files (D-R6) — excluded at every depth, case-insensitive. */
-const RESERVED_FILES = new Set(["index.md", "log.md"]);
-/** Upper bound on the bounded `content` FTS field (mirrors okf-adapter). */
-const MAX_CONTENT_CHARS = 100_000;
+import { hashContent, nonEmptyString, RESERVED_FILES, readTags, runBaseValidateChecks } from "./shared.js";
 /** The canonical (plural) subdir spellings writes normalize to (open-question-6). */
 const CANONICAL_COMMAND_DIR = "commands";
 const CANONICAL_AGENT_DIR = "agents";
 const CANONICAL_SKILL_DIR = "skills";
 const SKILL_MANIFEST = "SKILL.md";
-function toPosix(p) {
-    return p.replace(/\\/g, "/");
-}
 function isReserved(base) {
     return RESERVED_FILES.has(base.toLowerCase());
 }
@@ -122,7 +116,7 @@ export function recognizeToolDir(layout, c, file) {
         adapterId: layout.adapterId,
         type: cls.type,
         name,
-        content: body.length > MAX_CONTENT_CHARS ? body.slice(0, MAX_CONTENT_CHARS) : body,
+        content: body,
     };
     if (cls.type === "instruction")
         doc.ownsPresentation = true;

package/dist/core/adapter/adapters/website-snapshot-adapter.js

@@ -28,6 +28,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { parseFrontmatter, parseFrontmatterBlock } from "../../asset/frontmatter.js";
+import { toPosix } from "../../common.js";
 import { hashContent, nonEmptyString, runBaseValidateChecks } from "./shared.js";
 /** A snapshot bundle is single-component; its one component is `main`. */
 const COMPONENT_ID = "main";
@@ -37,11 +38,6 @@ const PAGES_PREFIX = "stash/knowledge/";
 const MANIFEST_FILE = "manifest.json";
 /** The tag the snapshot writer stamps on every crawled page. */
 const WEBSITE_TAG = "website";
-/** Upper bound on the bounded `content` FTS field (mirrors okf-adapter). */
-const MAX_CONTENT_CHARS = 100_000;
-function toPosix(p) {
-    return p.replace(/\\/g, "/");
-}
 function parseSnapshotFrontmatter(raw) {
     const out = { tags: [] };
     const block = parseFrontmatterBlock(raw);
@@ -98,7 +94,7 @@ function recognize(c, file) {
         ownsPresentation: true,
         type: "website",
         name,
-        content: body.length > MAX_CONTENT_CHARS ? body.slice(0, MAX_CONTENT_CHARS) : body,
+        content: body,
     };
     if (fm.description !== undefined)
         doc.description = fm.description;

package/dist/core/adapter/validate-context.js

@@ -48,9 +48,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { assetPathForName, stashDirFor } from "../asset/asset-placement.js";
 import { typeNameFromConceptId } from "../asset/resolve-ref.js";
-function toPosix(p) {
-    return p.replace(/\\/g, "/");
-}
+import { toPosix } from "../common.js";
 /** Build the overlay map, keyed by POSIX path relative to `root`. */
 function buildOverlay(root, changes) {
     const overlay = new Map();

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

@@ -25,10 +25,8 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { SCRIPT_EXTENSIONS, WORKFLOW_EXTENSIONS } from "../recognition-util.js";
-function toPosix(input) {
-    return input.replace(/\\/g, "/");
-}
+import { toPosix } from "../common.js";
+import { DERIVED_SUFFIX, SCRIPT_EXTENSIONS, WORKFLOW_EXTENSIONS } from "../recognition-util.js";
 const workflowSpec = {
     isRelevantFile: (fileName) => WORKFLOW_EXTENSIONS.includes(path.extname(fileName).toLowerCase()),
     toCanonicalName: (typeRoot, filePath) => {
@@ -247,10 +245,21 @@ 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. Every other placement type has exactly one inverse spelling.
+ * 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.
  */
 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/core/asset/frontmatter.js

@@ -207,6 +207,218 @@ export function spliceFrontmatterLine(raw, line) {
     lines.splice(closeIdx, 0, line);
     return lines.join("\n");
 }
+/**
+ * Strip one layer of matching quotes — frontmatter list items are often quoted
+ * refs. Written as an explicit char compare rather than a backreference regex
+ * on purpose: `scripts/lint-repository-sql.ts`'s comment/string stripper has no
+ * regex-literal awareness, so a literal holding an ODD number of quote
+ * characters desyncs its state machine and corrupts every match after it.
+ */
+function unquote(value) {
+    const trimmed = value.trim();
+    if (trimmed.length < 2)
+        return trimmed;
+    const first = trimmed[0];
+    if ((first === '"' || first === "'") && trimmed[trimmed.length - 1] === first)
+        return trimmed.slice(1, -1);
+    return trimmed;
+}
+/**
+ * Remove specific VALUES from one frontmatter list key, preserving every other
+ * byte — the counterpart to {@link spliceFrontmatterLine} for the
+ * `akm lint --prune-dangling-edges` repair (#884).
+ *
+ * Handles the three spellings a belief channel appears in: a block sequence
+ * (`contradictedBy:\n  - a`), an inline flow (`contradictedBy: [a, b]`), and a
+ * bare scalar (`contradictedBy: a`). When every value under the key is removed
+ * the key itself goes too — an empty `contradictedBy: []` is not the same
+ * assertion as no edge at all.
+ *
+ * Returns the rewritten source, or `null` when `raw` has no well-formed
+ * frontmatter block or nothing matched, so the caller can leave the file
+ * untouched and report the finding unfixed. Deliberately source-preserving:
+ * these are user-authored memories, and a repair must not silently reformat
+ * the frontmatter it was not asked to touch.
+ */
+export function removeFrontmatterListValues(raw, key, values) {
+    const remove = new Set(values.map((v) => unquote(v)));
+    if (remove.size === 0)
+        return null;
+    const lines = raw.split(/\r?\n/);
+    if (lines[0]?.trim() !== "---")
+        return null;
+    const closeIdx = lines.findIndex((l, i) => i > 0 && l.trim() === "---");
+    if (closeIdx === -1)
+        return null;
+    const out = [];
+    let changed = false;
+    let index = 0;
+    while (index < lines.length) {
+        const line = lines[index];
+        if (index === 0 || index >= closeIdx) {
+            out.push(line);
+            index += 1;
+            continue;
+        }
+        const kv = line.match(/^(\w[\w-]*):\s*(.*)$/);
+        if (kv === null || kv[1] !== key) {
+            out.push(line);
+            index += 1;
+            continue;
+        }
+        const rest = kv[2].trim();
+        // Inline flow: contradictedBy: [a, b]
+        const flow = rest.match(/^\[(.*)\]$/);
+        if (flow !== null) {
+            const kept = flow[1]
+                .split(",")
+                .map((item) => item.trim())
+                .filter(Boolean)
+                .filter((item) => !remove.has(unquote(item)));
+            const original = flow[1].split(",").filter((s) => s.trim().length > 0).length;
+            if (kept.length !== original) {
+                changed = true;
+                if (kept.length > 0)
+                    out.push(`${key}: [${kept.join(", ")}]`);
+            }
+            else {
+                out.push(line);
+            }
+            index += 1;
+            continue;
+        }
+        // Bare scalar: contradictedBy: a
+        if (rest !== "") {
+            if (remove.has(unquote(rest)))
+                changed = true;
+            else
+                out.push(line);
+            index += 1;
+            continue;
+        }
+        // Block sequence: the key line, then `  - value` items.
+        const header = line;
+        const items = [];
+        let cursor = index + 1;
+        while (cursor < closeIdx) {
+            const itemMatch = lines[cursor].match(/^\s+-\s*(.*)$/);
+            if (itemMatch === null)
+                break;
+            items.push(lines[cursor]);
+            cursor += 1;
+        }
+        const kept = items.filter((item) => !remove.has(unquote(item.replace(/^\s*-\s*/, ""))));
+        if (kept.length !== items.length) {
+            changed = true;
+            if (kept.length > 0) {
+                out.push(header);
+                out.push(...kept);
+            }
+        }
+        else {
+            out.push(header);
+            out.push(...items);
+        }
+        index = cursor;
+    }
+    return changed ? out.join("\n") : null;
+}
+/**
+ * Rewrite specific VALUES in one frontmatter list key to new spellings,
+ * preserving every other byte — the rename counterpart to
+ * {@link removeFrontmatterListValues}, used by `akm lint --fix` to migrate
+ * retired `type:slug` xref values (`xrefs:`/`supersededBy:`/`contradictedBy:`)
+ * to their conceptId form once resolution confirms the rewritten spelling
+ * still points at a real asset.
+ *
+ * Handles the same three spellings a belief channel appears in: a block
+ * sequence, an inline flow, and a bare scalar. `replacements` maps an
+ * unquoted OLD value to its NEW value; a value not present in the map is left
+ * untouched byte-for-byte (including any quoting it had).
+ *
+ * Returns the rewritten source, or `null` when `raw` has no well-formed
+ * frontmatter block or nothing matched, so the caller can leave the file
+ * untouched. Deliberately source-preserving, like its sibling.
+ */
+export function rewriteFrontmatterListValue(raw, key, replacements) {
+    if (replacements.size === 0)
+        return null;
+    const lines = raw.split(/\r?\n/);
+    if (lines[0]?.trim() !== "---")
+        return null;
+    const closeIdx = lines.findIndex((l, i) => i > 0 && l.trim() === "---");
+    if (closeIdx === -1)
+        return null;
+    const out = [];
+    let changed = false;
+    let index = 0;
+    while (index < lines.length) {
+        const line = lines[index];
+        if (index === 0 || index >= closeIdx) {
+            out.push(line);
+            index += 1;
+            continue;
+        }
+        const kv = line.match(/^(\w[\w-]*):\s*(.*)$/);
+        if (kv === null || kv[1] !== key) {
+            out.push(line);
+            index += 1;
+            continue;
+        }
+        const rest = kv[2].trim();
+        // Inline flow: xrefs: [a, b]
+        const flow = rest.match(/^\[(.*)\]$/);
+        if (flow !== null) {
+            const items = flow[1].split(",").map((item) => item.trim());
+            const nextItems = items.map((item) => {
+                if (!item)
+                    return item;
+                const replacement = replacements.get(unquote(item));
+                if (replacement === undefined)
+                    return item;
+                changed = true;
+                return replacement;
+            });
+            out.push(items.length > 0 && items[0] !== "" ? `${kv[1]}: [${nextItems.join(", ")}]` : line);
+            index += 1;
+            continue;
+        }
+        // Bare scalar: xrefs: a
+        if (rest !== "") {
+            const replacement = replacements.get(unquote(rest));
+            if (replacement === undefined) {
+                out.push(line);
+            }
+            else {
+                changed = true;
+                out.push(`${kv[1]}: ${replacement}`);
+            }
+            index += 1;
+            continue;
+        }
+        // Block sequence: the key line, then `  - value` items.
+        out.push(line);
+        let cursor = index + 1;
+        while (cursor < closeIdx) {
+            const itemLine = lines[cursor];
+            const itemMatch = itemLine.match(/^(\s*-\s*)(.*)$/);
+            if (itemMatch === null)
+                break;
+            const [, prefix, value] = itemMatch;
+            const replacement = replacements.get(unquote(value));
+            if (replacement === undefined) {
+                out.push(itemLine);
+            }
+            else {
+                changed = true;
+                out.push(`${prefix}${replacement}`);
+            }
+            cursor += 1;
+        }
+        index = cursor;
+    }
+    return changed ? out.join("\n") : null;
+}
 /**
  * Parse a YAML scalar value (string, boolean, or number).
  *

package/dist/core/asset/memory-archive.js

@@ -0,0 +1,97 @@
+// 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/.
+/**
+ * The memory-cleanup archive as a REF-RESOLUTION surface (#884).
+ *
+ * `analyzeMemoryCleanup`'s prune (`commands/improve/memory/memory-improve.ts`
+ * `#archiveMemory`) does not delete a memory: it `rename`s the file under
+ * `.akm/memory-cleanup/archive/<stamp>-<ref>/<originalPath>` and writes a
+ * sibling `cleanup.md` audit asset carrying `ref` / `originalPath` /
+ * `archivedPath`. The bytes and the identity both survive — but the ref stops
+ * resolving at its ORIGINAL location, so every inbound belief edge
+ * (`contradictedBy` / `supersededBy`) pointing at the pruned memory becomes a
+ * `missing-ref` the moment #882 made those channels validatable.
+ *
+ * That is the #884 defect, and the archive already holds everything needed to
+ * fix it: the audit record IS a tombstone. This module reads those tombstones
+ * so ref resolution can answer "archived" instead of "missing". Resolution
+ * stays non-destructive — pruning never rewrites an unrelated memory's
+ * frontmatter, and the contradiction an edge records is preserved rather than
+ * erased (the concern #884 raised against a bare edge-scrub).
+ *
+ * A ref whose target has NO tombstone and no file is genuinely dangling — it
+ * was removed by something other than prune (a hand `git rm`, an older
+ * release). Those stay reported; clearing them mutates user data and so is
+ * gated behind `akm lint --prune-dangling-edges`.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { parseFrontmatter } from "./frontmatter.js";
+/** Stash-relative root the prune path archives into. Must match `memory-improve.ts#createArchiveDir`. */
+export const MEMORY_ARCHIVE_REL = ".akm/memory-cleanup/archive";
+/** Filename of the per-archive audit asset written alongside the archived memory. */
+const AUDIT_FILENAME = "cleanup.md";
+/**
+ * Cache keyed by stash root. A lint sweep resolves thousands of refs against a
+ * directory that only the prune path ever writes, so the scan runs once per
+ * root instead of once per missing ref.
+ */
+const cache = new Map();
+/** @internal Drop the memoized scans — process-global state needs a reset seam for tests (#785). */
+export function resetMemoryArchiveCache() {
+    cache.clear();
+}
+/**
+ * Every stash-relative `originalPath` archived under `root`, i.e. the set of
+ * paths that USED to hold a memory and now hold a tombstone instead.
+ *
+ * Unreadable or malformed audit records are skipped rather than thrown: a
+ * corrupt tombstone must degrade to "this ref is missing" (the pre-#884
+ * answer), never break the whole lint sweep.
+ */
+export function archivedOriginalPaths(root) {
+    const cached = cache.get(root);
+    if (cached !== undefined)
+        return cached;
+    const paths = new Set();
+    const archiveRoot = path.join(root, MEMORY_ARCHIVE_REL);
+    let entries;
+    try {
+        entries = fs.readdirSync(archiveRoot, { withFileTypes: true });
+    }
+    catch {
+        cache.set(root, paths); // no archive dir — nothing was ever pruned here
+        return paths;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        let raw;
+        try {
+            raw = fs.readFileSync(path.join(archiveRoot, entry.name, AUDIT_FILENAME), "utf8");
+        }
+        catch {
+            continue;
+        }
+        let originalPath;
+        try {
+            originalPath = parseFrontmatter(raw).data.originalPath;
+        }
+        catch {
+            continue;
+        }
+        if (typeof originalPath === "string" && originalPath.trim().length > 0) {
+            paths.add(originalPath.trim().replace(/\\/g, "/"));
+        }
+    }
+    cache.set(root, paths);
+    return paths;
+}
+/**
+ * True when `relPath` (stash-relative, POSIX) names a memory that prune
+ * archived — the ref resolves to a tombstone rather than to nothing.
+ */
+export function isArchivedRelPath(relPath, root) {
+    return archivedOriginalPaths(root).has(relPath.replace(/\\/g, "/"));
+}

package/dist/core/common.js

@@ -277,8 +277,14 @@ function isValidDirectory(dir) {
     try {
         return fs.statSync(dir).isDirectory();
     }
-    catch {
-        return false;
+    catch (error) {
+        // Genuinely absent — the caller's "not found" fallback applies. Any other
+        // stat failure (e.g. EACCES) is not "doesn't exist"; treating it as such
+        // produced the wrong message ("Run akm bundle create") for a directory
+        // that exists but cannot be read.
+        if (hasErrnoCode(error, "ENOENT"))
+            return false;
+        throw new ConfigError(`Unable to read bundle directory at "${dir}".`, "STASH_DIR_UNREADABLE");
     }
 }
 /**
@@ -356,6 +362,10 @@ function readStashDirFromConfig() {
 export function toPosix(input) {
     return input.replace(/\\/g, "/");
 }
+/** Locale-independent code-point ordering — a stable `Array.prototype.sort` comparator for strings (paths, names, ids). */
+export function compareCodePoints(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
 export function hasErrnoCode(error, code) {
     if (typeof error !== "object" || error === null || !("code" in error))
         return false;
@@ -873,7 +883,61 @@ export function asNonEmptyString(value) {
     const trimmed = value.trim();
     return trimmed.length > 0 ? trimmed : undefined;
 }
+// ── env-file assignment scanning ─────────────────────────────────────────────
+/** Matches a `KEY=value` assignment line, capturing only the key. */
+export const ENV_ASSIGN_LINE_RE = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/;
+/** Scan lines and return KEY names in file order, without duplicates. */
+export function scanEnvKeyNames(text) {
+    const keys = [];
+    const seen = new Set();
+    for (const line of text.split(/\r?\n/)) {
+        const m = line.match(ENV_ASSIGN_LINE_RE);
+        if (!m)
+            continue;
+        const key = m[1];
+        if (!key)
+            continue;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        keys.push(key);
+    }
+    return keys;
+}
+/** True when `value` contains no lone/unpaired UTF-16 surrogate (every surrogate is part of a valid pair). */
+export function wellFormedUnicode(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code >= 0xd800 && code <= 0xdbff) {
+            const next = value.charCodeAt(index + 1);
+            if (!(next >= 0xdc00 && next <= 0xdfff))
+                return false;
+            index += 1;
+        }
+        else if (code >= 0xdc00 && code <= 0xdfff)
+            return false;
+    }
+    return true;
+}
 // ── Generic data utilities ───────────────────────────────────────────────────
+/**
+ * Narrow an unknown value to a plain-ish record: an `object` that is neither
+ * `null` nor an `Array`. Does not distinguish a literal `{}` from a `Date`,
+ * `Map`, or class instance — callers that need that distinction use a
+ * stricter predicate instead.
+ */
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** `JSON.parse` that returns `undefined` instead of throwing. */
+export function tryParseJson(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Coerce an unknown value to a filtered, trimmed string array.
  * Non-strings and empty/whitespace-only entries are dropped.