akm-cli 0.9.0-rc.9 → 0.9.1-beta.1

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

@@ -25,12 +25,106 @@
  *    WARNING (consumers tolerate broken links). Reads go through
  *    `ctx.readFile`; ref existence via `ctx.resolveRef`. Never touches the live
  *    filesystem.
- *  - placeNew / directoryList / looksLikeRoot per §5 / §1.2.
+ *  - directoryList / looksLikeRoot per §5 / §1.2. Authoring is deliberately
+ *    absent; AKM-native writers fail before mutating an OKF bundle.
  */
 import fs from "node:fs";
 import path from "node:path";
 import { parseFrontmatter } from "../../asset/frontmatter.js";
 import { hashContent, nonEmptyString, 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",
+    "title",
+    "description",
+    "tags",
+    "timestamp",
+    "generated",
+    "verified",
+    "sources",
+    "status",
+    "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))
+        return undefined;
+    const by = nonEmptyString(value.by);
+    if (by === undefined)
+        return undefined;
+    const at = nonEmptyString(value.at);
+    return at !== undefined ? { by, at } : { by };
+}
+/**
+ * Parse the `verified:` family. v0.2 permits EITHER a list of `{by, at?}`
+ * mappings OR a single mapping written without the list dash (the shorthand
+ * form) — both normalize to a non-empty array here. Malformed entries are
+ * dropped individually; an entirely-empty/malformed result is `undefined`
+ * rather than `[]` (mirrors every other optional-field convention on this
+ * adapter: absent, not empty).
+ */
+function parseVerified(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const candidates = Array.isArray(value) ? value : [value];
+    const out = [];
+    for (const candidate of candidates) {
+        const parsed = parseActorMapping(candidate);
+        if (parsed)
+            out.push(parsed);
+    }
+    return out.length > 0 ? out : undefined;
+}
+/**
+ * Parse the `sources:` object-list family. Each entry needs at minimum a
+ * non-empty `resource`; entries failing that are dropped individually (never
+ * rejects the document). This is a DIFFERENT shape from the AKM-native
+ * `IndexDocument.sources: string[]` (wiki citations) — the two are never
+ * mixed, hence the caller lands this under `provenance.sources` instead.
+ */
+function parseOkfSources(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const out = [];
+    for (const item of value) {
+        if (!isPlainObject(item))
+            continue;
+        const resource = nonEmptyString(item.resource);
+        if (resource === undefined)
+            continue;
+        const entry = { resource };
+        const id = nonEmptyString(item.id);
+        if (id !== undefined)
+            entry.id = id;
+        const title = nonEmptyString(item.title);
+        if (title !== undefined)
+            entry.title = title;
+        const author = nonEmptyString(item.author);
+        if (author !== undefined)
+            entry.author = author;
+        if (typeof item.usage_count === "number" && Number.isFinite(item.usage_count)) {
+            entry.usage_count = item.usage_count;
+        }
+        const lastModified = nonEmptyString(item.last_modified);
+        if (lastModified !== undefined)
+            entry.last_modified = lastModified;
+        out.push(entry);
+    }
+    return out.length > 0 ? out : undefined;
+}
+/** Parse the `status:` lifecycle field — a strict whitelist; any other value (including a foreign/future status) is left unset rather than guessed at. */
+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. */
@@ -59,13 +153,24 @@ function isReservedFileName(name) {
  */
 export function resolveOkfLinks(body, fileRelPath) {
     const dir = path.posix.dirname(toPosix(fileRelPath));
-    const linkRe = /\[[^\]]*\]\(([^)]+)\)/g;
+    const definitions = new Map();
+    for (const match of body.matchAll(/^\s*\[([^\]]+)\]:\s*(\S+)/gm)) {
+        definitions.set(match[1].trim().toLowerCase(), match[2]);
+    }
+    const candidates = [];
+    for (const match of body.matchAll(/\[[^\]]*\]\(([^)]+)\)/g)) {
+        candidates.push({ index: match.index, target: match[1] });
+    }
+    for (const match of body.matchAll(/(?<!!)\[[^\]]*\]\[([^\]]+)\]/g)) {
+        const target = definitions.get(match[1].trim().toLowerCase());
+        if (target)
+            candidates.push({ index: match.index, target });
+    }
+    candidates.sort((a, b) => a.index - b.index);
     const out = [];
     const seen = new Set();
-    let match;
-    // biome-ignore lint/suspicious/noAssignInExpressions: idiomatic regex loop
-    while ((match = linkRe.exec(body)) !== null) {
-        let target = match[1].trim();
+    for (const candidate of candidates) {
+        let target = candidate.target.trim();
         // Drop an optional markdown link title: `[x](/a.md "Title")`.
         const wsIdx = target.search(/\s/);
         if (wsIdx >= 0)
@@ -127,8 +232,33 @@ function recognize(c, file) {
     const name = nonEmptyString(data.title) ?? lastSegment;
     const description = nonEmptyString(data.description);
     const tags = readTags(data.tags);
-    const updated = nonEmptyString(data.timestamp);
     const links = resolveOkfLinks(body, file.relPath);
+    // v0.2 trust/provenance/lifecycle families (§0.1, okf-support.md v0.2 note).
+    // `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 generatedAt = generatedMapping ? nonEmptyString(generatedMapping.at) : undefined;
+    const generatedBy = generatedMapping ? nonEmptyString(generatedMapping.by) : undefined;
+    const legacyTimestamp = nonEmptyString(data.timestamp);
+    const updated = generatedAt ?? legacyTimestamp;
+    const verified = parseVerified(data.verified);
+    const okfSources = parseOkfSources(data.sources);
+    const provenance = generatedBy !== undefined || generatedAt !== undefined || verified !== undefined || okfSources !== undefined
+        ? {
+            ...(generatedBy !== undefined ? { generatedBy } : {}),
+            ...(generatedAt !== undefined ? { generatedAt } : {}),
+            ...(verified !== undefined ? { verified } : {}),
+            ...(okfSources !== undefined ? { sources: okfSources } : {}),
+        }
+        : undefined;
+    const lifecycleStatus = parseLifecycleStatus(data.status);
+    const staleAfter = nonEmptyString(data.stale_after);
+    // `okf_version` is upstream-declared only on a bundle-root `index.md` (never
+    // indexed as a concept, §5) — read defensively from any concept anyway
+    // (best-effort, conformance Rule 9); a producer that also tags ordinary
+    // concepts with it is neither rejected nor silently ignored.
+    const okfVersion = nonEmptyString(data.okf_version);
     const doc = {
         ref: `${c.id}//${conceptId}`,
         bundle: c.id,
@@ -139,6 +269,7 @@ function recognize(c, file) {
         // incrementality/fingerprints (`types.ts` hash doc comment).
         hash: hashContent(raw),
         adapterId: "okf",
+        ownsPresentation: true,
         type,
         name,
         content: body.length > MAX_CONTENT_CHARS ? body.slice(0, MAX_CONTENT_CHARS) : body,
@@ -151,6 +282,17 @@ function recognize(c, file) {
         doc.updated = updated;
     if (links.length > 0)
         doc.links = links;
+    if (provenance !== undefined)
+        doc.provenance = provenance;
+    if (lifecycleStatus !== undefined)
+        doc.lifecycleStatus = lifecycleStatus;
+    if (staleAfter !== undefined)
+        doc.staleAfter = staleAfter;
+    if (okfVersion !== undefined)
+        doc.okfVersion = okfVersion;
+    const extras = Object.fromEntries(Object.entries(data).filter(([key]) => !CONSUMED_FRONTMATTER_KEYS.includes(key)));
+    if (Object.keys(extras).length > 0)
+        doc.documentJson = extras;
     return doc;
 }
 async function validate(c, changes, ctx) {
@@ -165,14 +307,11 @@ async function validate(c, changes, ctx) {
         const fileName = relPath.split("/").pop() ?? relPath;
         const reserved = isReservedFileName(fileName);
         const parsed = parseFrontmatter(raw);
-        // Base checks (unquoted-colon / missing-updated / stale-path / missing-ref).
+        // Base checks shared with native AKM formats. OKF's timestamp is optional,
+        // so the AKM-specific freshness diagnostic is removed unconditionally.
         const base = await runBaseValidateChecks(relPath, parsed, c.root, ctx);
-        // §0.1: for OKF content a `timestamp` satisfies the freshness requirement
-        // (the base-linter's `missing-updated` maps to `timestamp`). Suppress the
-        // `missing-updated` diagnostic when a non-empty `timestamp` is present.
-        const hasTimestamp = nonEmptyString(parsed.data.timestamp) !== undefined;
         for (const diag of base) {
-            if (hasTimestamp && diag.issue === "missing-updated")
+            if (diag.issue === "missing-updated")
                 continue;
             diagnostics.push(diag);
         }
@@ -208,16 +347,45 @@ export const okfAdapter = {
     extensions: [".md"],
     recognize,
     validate,
-    /** `<c.root>/<conceptId>.md` (§5). */
-    placeNew(c, conceptId) {
-        return path.join(c.root, `${conceptId}.md`);
-    },
     /** OKF concepts live anywhere under the component root (§5). */
     directoryList(_c) {
         return ["."];
     },
-    /** Install-time probe: a root is an OKF bundle when it has a root `index.md` (§1.2; `okf_version` NOT required). */
+    /**
+     * Install-time probe. A root index is sufficient; an index-less root is also
+     * OKF when it contains at least one conformant concept with a non-empty open
+     * `type`. More-specific native adapters run before this portable baseline.
+     */
     looksLikeRoot(root) {
-        return fs.existsSync(path.join(root, "index.md"));
+        if (fs.existsSync(path.join(root, "index.md")))
+            return true;
+        const stack = [root];
+        while (stack.length > 0) {
+            const current = stack.pop();
+            if (!current)
+                continue;
+            let entries;
+            try {
+                entries = fs.readdirSync(current, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries) {
+                if (entry.isSymbolicLink() || entry.name === ".git")
+                    continue;
+                const absolute = path.join(current, entry.name);
+                if (entry.isDirectory()) {
+                    stack.push(absolute);
+                    continue;
+                }
+                if (!entry.isFile() || !entry.name.toLowerCase().endsWith(".md") || isReservedFileName(entry.name))
+                    continue;
+                const type = nonEmptyString(parseFrontmatter(fs.readFileSync(absolute, "utf8")).data.type);
+                if (type)
+                    return true;
+            }
+        }
+        return false;
     },
 };

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

@@ -49,6 +49,7 @@
  */
 import { createHash } from "node:crypto";
 import { parseFrontmatter } from "../../asset/frontmatter.js";
+import { checkUnquotedDescriptionColon } from "../../asset/frontmatter-lint.js";
 // ── Small pure helpers, reused across the concrete adapters ──────────────────
 /** Content hash feeding `IndexDocument.hash` (incrementality/fingerprints, `types.ts` doc comment). */
 export function hashContent(content) {
@@ -69,23 +70,6 @@ export function readTags(value) {
     return tags.length > 0 ? tags : undefined;
 }
 // ── Base validate checks (port of `BaseLinter.runBaseChecks`) ────────────────
-function checkUnquotedColon(frontmatterText) {
-    if (!frontmatterText)
-        return null;
-    for (const line of frontmatterText.split(/\r?\n/)) {
-        const match = line.match(/^description:\s*(.*)/);
-        if (!match)
-            continue;
-        const value = match[1].trim();
-        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
-            return null;
-        }
-        if (value.includes(":")) {
-            return `description value contains unquoted colon: ${value}`;
-        }
-    }
-    return null;
-}
 function checkMissingUpdated(data, frontmatterText) {
     return frontmatterText !== null && !("updated" in data);
 }
@@ -207,7 +191,7 @@ function readRefStringOrArray(value) {
 export async function runBaseValidateChecks(relPath, parsed, componentRoot, ctx) {
     const diagnostics = [];
     const { data, content: body, frontmatter } = parsed;
-    const unquotedColonDetail = checkUnquotedColon(frontmatter);
+    const unquotedColonDetail = checkUnquotedDescriptionColon(frontmatter);
     if (unquotedColonDetail) {
         diagnostics.push({ file: relPath, issue: "unquoted-colon", detail: unquotedColonDetail, fixed: false });
     }
@@ -228,7 +212,7 @@ export async function runBaseValidateChecks(relPath, parsed, componentRoot, ctx)
         if (found !== null)
             continue;
         const portableHint = candidate.startsWith(componentRoot)
-            ? ` (portable form: $AKM_STASH_DIR${candidate.slice(componentRoot.length)})`
+            ? ` (portable form: $AKM_BUNDLE_DIR${candidate.slice(componentRoot.length)})`
             : "";
         diagnostics.push({
             file: relPath,

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

@@ -41,9 +41,12 @@
  * ── Cycle-safety ──
  *
  * Imported only by `claude-adapter.ts` / `opencode-adapter.ts` (themselves
- * imported only by the test-only `adapters/index.ts` barrel), so this leaf can
- * never gain an inbound edge from a cycle participant. It value-imports only
- * pure leaves (`shared`, `akm-lint`, `frontmatter`) plus Node builtins.
+ * imported by the `adapters/index.ts` barrel — NOT test-only: `core/adapter/
+ * registry.ts:33` imports it in production for the frozen `BUILTIN_ADAPTERS`
+ * list). This leaf still can never gain an inbound edge from a cycle
+ * participant, since nothing on that import chain imports back into it. It
+ * value-imports only pure leaves (`shared`, `akm-lint`, `frontmatter`) plus
+ * Node builtins.
  */
 import path from "node:path";
 import { parseFrontmatter } from "../../asset/frontmatter.js";
@@ -121,6 +124,8 @@ export function recognizeToolDir(layout, c, file) {
         name,
         content: body.length > MAX_CONTENT_CHARS ? body.slice(0, MAX_CONTENT_CHARS) : body,
     };
+    if (cls.type === "instruction")
+        doc.ownsPresentation = true;
     if (description !== undefined)
         doc.description = description;
     if (tags !== undefined)
@@ -180,9 +185,11 @@ export async function validateToolDir(layout, c, changes, ctx) {
             continue;
         const relPath = toPosix(change.path);
         // The one coded skill check (missing-skill-md) fires on ANY change under a
-        // `skills/<name>/…` package (self-gated + deduped), even a bundled resource —
-        // mirrors the akm adapter's per-change SkillLinter.lintDirectory pass.
-        diagnostics.push(...(await skillDirectoryDiagnostics(relPath, seenSkillDirs, ctx)));
+        // `<skillDir>/<name>/…` package (self-gated + deduped), even a bundled
+        // resource — mirrors the akm adapter's per-change SkillLinter.lintDirectory
+        // pass. `layout.skillDirs` is passed so opencode's singular `skill/` alias
+        // is checked identically to `skills/` (issue #774).
+        diagnostics.push(...(await skillDirectoryDiagnostics(relPath, seenSkillDirs, ctx, layout.skillDirs)));
         const cls = classify(change.path, layout);
         if (cls === null)
             continue;

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

@@ -95,6 +95,7 @@ function recognize(c, file) {
         path: file.absPath,
         hash: hashContent(raw),
         adapterId: "website-snapshot",
+        ownsPresentation: true,
         type: "website",
         name,
         content: body.length > MAX_CONTENT_CHARS ? body.slice(0, MAX_CONTENT_CHARS) : body,

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

@@ -0,0 +1,17 @@
+// 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`. */
+export function detectAdapterId(root, fallback = "akm") {
+    for (const adapter of getAdapters()) {
+        try {
+            if (adapter.looksLikeRoot?.(root) === true)
+                return adapter.id;
+        }
+        catch {
+            // An unreadable or racing probe does not claim the bundle.
+        }
+    }
+    return fallback;
+}

package/dist/core/adapter/recognize-match.js

@@ -1,19 +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/.
-import { directoryMatcher, extensionMatcher, parentDirHintMatcher, smartMdMatcher, workflowProgramMatcher, } from "../../indexer/walk/matchers.js";
+import { directoryMatcher, extensionMatcher, parentDirHintMatcher, smartMdMatcher } from "../../indexer/walk/matchers.js";
 /**
- * The five builtin matchers, in registration order. The array index IS the
+ * The four builtin matchers, in registration order. The array index IS the
  * registration index `runMatchers` uses for tie-breaking. (The `wiki` matcher
  * was removed in chunk 4 — the wiki asset-type is retired; LLM Wiki content is
- * served by the first-class `llm-wiki` adapter, not the akm adapter.)
+ * served by the first-class `llm-wiki` adapter, not the akm adapter. The YAML
+ * workflow-program matcher was removed by workflow-format-unification — one
+ * workflow format now, recognized by frontmatter `type: workflow` or
+ * residence under `workflows/`, both already covered by the remaining four.)
  */
 const AKM_MATCHERS = [
     extensionMatcher,
     directoryMatcher,
     parentDirHintMatcher,
     smartMdMatcher,
-    workflowProgramMatcher,
 ];
 /**
  * Synchronous reproduction of `file-context.ts#runMatchers`'s arbitration

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

@@ -0,0 +1,214 @@
+// 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 ONE core {@link ValidateContext} implementation — akm 0.9.0 chunk-2/lint
+ * follow-up ("make `validate()` genuinely load-bearing").
+ *
+ * `BundleAdapter.validate()` (`./bundle-adapter.ts`) is a REQUIRED interface
+ * method whose contract is explicit and normative (`./bundle-adapter.ts:96-100`
+ * / the format-neutral spec §12.1): the adapter MUST NOT write and MUST NOT
+ * read the live filesystem — `ctx` serves the run's on-disk SNAPSHOT WITH the
+ * caller's pending {@link FileChange}s overlaid, plus a read-only `resolveRef`
+ * for link/xref existence. That overlay is meant to be built ONCE, centrally —
+ * "one core overlay implementation, not one per adapter" (the interface's own
+ * words) — so every `validate()` caller shares identical overlay semantics
+ * rather than each hand-rolling its own (as every adapter's own test suite has
+ * done up to now, see e.g. `tests/core/adapter/okf-adapter.test.ts`'s
+ * `overlayCtx`/`diskCtx`).
+ *
+ * The two production callers wired onto this factory:
+ *   - `akm lint`'s non-akm adapter dispatch (`commands/lint/index.ts`) — a
+ *     plain sweep with NO pending changes, so the overlay is empty and every
+ *     read falls straight through to disk.
+ *   - the proposal promotion preflight (`commands/proposal/repository.ts`
+ *     `preflightProposalPromotion`) — the one proposal's own `changes` are the
+ *     overlay, so `validate()` sees the bundle AS IT WOULD LOOK the instant
+ *     after the transaction commits, without that transaction ever touching
+ *     disk.
+ *
+ * ── resolveRef ──
+ *
+ * A bare (unqualified) `conceptId` is resolved as BOTH:
+ *   1. the AKM placement-derived path (`typeNameFromConceptId` + `stashDirFor`
+ *      + `assetPathForName` — the exact derivation `commands/lint/base-linter.ts
+ *      #refToRelPath` already uses for the akm-native `missing-ref` check); and
+ *   2. the DIRECT component-relative spelling (`<conceptId>.md`, and the bare
+ *      `<conceptId>` for an extensionless asset) — the form every non-akm
+ *      adapter's OWN conceptId already IS (OKF: path − `.md`; llm-wiki: same).
+ * A `bundle//conceptId`-qualified ref has its bundle prefix stripped before
+ * resolution — mirroring `base-linter.ts#classifyConceptRef`'s existing
+ * behavior (the legacy resolver has never scoped-by-bundle-name either; it
+ * searches every configured stash root for the bare conceptId). Existence is
+ * checked against the PRIMARY root (with the pending-changes overlay applied)
+ * first, then each extra root (disk only — a pending transaction never
+ * targets more than one bundle).
+ */
+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, "/");
+}
+/** Build the overlay map, keyed by POSIX path relative to `root`. */
+function buildOverlay(root, changes) {
+    const overlay = new Map();
+    for (const change of changes) {
+        const relKey = toPosix(path.isAbsolute(change.path) ? path.relative(root, change.path) : change.path);
+        if (!relKey || relKey.startsWith(".."))
+            continue; // outside root — not this context's concern
+        if (change.op === "delete") {
+            overlay.set(relKey, null);
+            continue;
+        }
+        if (change.after !== undefined)
+            overlay.set(relKey, change.after);
+    }
+    return overlay;
+}
+function readDisk(absPath) {
+    try {
+        return fs.readFileSync(absPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function existsOnDiskOrOverlay(relPath, root, overlay) {
+    const key = toPosix(relPath);
+    // Overlay entries are pending file contents by construction, so a present
+    // non-null entry is always a file.
+    if (overlay?.has(key))
+        return overlay.get(key) !== null;
+    try {
+        // `isFile()`, not `existsSync()`: a ref naming a DIRECTORY (e.g. a
+        // `pages/foo/` dir alongside no `pages/foo.md`) must not count as a
+        // resolved target — that would silently suppress a real
+        // `missing-ref`/`broken-xref` diagnostic.
+        return fs.statSync(path.join(root, relPath)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Refs come from bundle CONTENT (link targets, xrefs, `sources:` entries), so
+ * they are untrusted input. A ref must stay inside the bundle root: reject
+ * absolute paths and any `..` segment before joining, so content can never
+ * probe for existence outside its own bundle (nor report a resolved `path`
+ * pointing there). Mirrors the `isWithin` containment rule the write path
+ * already enforces in `core/write-source.ts`.
+ */
+function refEscapesBundle(conceptId) {
+    if (path.isAbsolute(conceptId) || conceptId.startsWith("/"))
+        return true;
+    return toPosix(conceptId)
+        .split("/")
+        .some((segment) => segment === "..");
+}
+/**
+ * Every on-disk relative path a bare `conceptId` might resolve to: the AKM
+ * placement-derived path (when the leading segment names a known placement
+ * stash-subdir) and the direct component-relative spellings every non-akm
+ * adapter's own conceptId already uses. Order doesn't matter — the caller
+ * checks all of them.
+ */
+function candidateRelPaths(conceptId) {
+    const candidates = [];
+    const parts = typeNameFromConceptId(conceptId);
+    if (parts !== undefined) {
+        const typeDir = stashDirFor(parts.type);
+        if (typeDir !== undefined)
+            candidates.push(assetPathForName(parts.type, typeDir, parts.name));
+    }
+    candidates.push(`${conceptId}.md`);
+    candidates.push(conceptId);
+    return candidates;
+}
+/** Strip an optional `#fragment` (export selector) — never part of the on-disk identity. */
+function stripFragment(ref) {
+    const hashIdx = ref.indexOf("#");
+    return hashIdx >= 0 ? ref.slice(0, hashIdx) : ref;
+}
+/**
+ * Strip an optional `bundle//` qualifier. Mirrors `base-linter.ts
+ * #classifyConceptRef`'s existing behavior: the legacy missing-ref checker has
+ * never resolved a qualifier against a NAMED bundle either — it searches every
+ * configured stash root for the bare conceptId. Keeping that same leniency
+ * here means this resolver's answers agree with today's `akm lint` for every
+ * ref shape that already worked.
+ */
+function stripBundlePrefix(ref) {
+    const boundary = ref.indexOf("//");
+    return boundary >= 0 ? ref.slice(boundary + 2) : ref;
+}
+/**
+ * Build the ONE core {@link ValidateContext}: reads/lookups served from the
+ * on-disk snapshot rooted at `options.root` (+ `options.extraRoots` for
+ * cross-bundle ref existence) WITH `options.changes` overlaid on `options.root`
+ * — never a write, never a live-FS read beyond that snapshot.
+ */
+export function createValidateContext(options) {
+    const root = options.root;
+    const extraRoots = options.extraRoots ?? [];
+    const overlay = buildOverlay(root, options.changes ?? []);
+    async function readFile(p) {
+        // An absolute candidate (e.g. a `stale-path` scan hit, which is always an
+        // absolute host path) bypasses the overlay — it can never name a pending
+        // change's stash-relative path, and reads straight from disk (the base
+        // checks' existing "does this literal absolute path exist" question).
+        if (path.isAbsolute(p))
+            return readDisk(p);
+        const key = toPosix(p);
+        if (overlay.has(key))
+            return overlay.get(key) ?? null;
+        return readDisk(path.join(root, p));
+    }
+    async function list(dir) {
+        const abs = path.isAbsolute(dir) ? dir : path.join(root, dir);
+        const relDir = toPosix(path.isAbsolute(dir) ? path.relative(root, dir) : dir);
+        const names = new Set();
+        try {
+            for (const entry of fs.readdirSync(abs))
+                names.add(entry);
+        }
+        catch {
+            // directory may not exist on disk yet — the overlay can still populate it
+        }
+        const prefix = relDir === "." || relDir === "" ? "" : `${relDir}/`;
+        for (const [key, value] of overlay) {
+            if (prefix.length > 0 && !key.startsWith(prefix))
+                continue;
+            const rest = prefix.length > 0 ? key.slice(prefix.length) : key;
+            if (rest.length === 0 || rest.includes("/"))
+                continue; // only direct children
+            if (value === null)
+                names.delete(rest);
+            else
+                names.add(rest);
+        }
+        return [...names];
+    }
+    async function resolveRef(ref) {
+        const conceptId = stripBundlePrefix(stripFragment(ref)).trim();
+        if (!conceptId)
+            return { exists: false };
+        if (refEscapesBundle(conceptId))
+            return { exists: false };
+        const candidates = candidateRelPaths(conceptId);
+        const roots = [
+            { root, usesOverlay: true },
+            ...extraRoots.map((r) => ({ root: r, usesOverlay: false })),
+        ];
+        for (const { root: candidateRoot, usesOverlay } of roots) {
+            for (const relPath of candidates) {
+                if (existsOnDiskOrOverlay(relPath, candidateRoot, usesOverlay ? overlay : null)) {
+                    return { exists: true, path: path.join(candidateRoot, relPath) };
+                }
+            }
+        }
+        return { exists: false };
+    }
+    return { readFile, list, resolveRef };
+}